Skip to main content
The @agentmark-ai/mcp-server package exposes the AgentMark gateway to AI-powered editors over the Model Context Protocol. Point it at your local agentmark dev server or at AgentMark Cloud, and your AI assistant can list traces, drill into spans, check capabilities, write scores, and call any other gateway operation — without leaving your editor.
This is different from the docs MCP described in AI editor integration, which is a remote server that helps your editor author .prompt.mdx files. This package connects to your gateway (local or Cloud) to query and debug live data.

​
How tools are generated

The server does not ship a fixed, hand-written tool list. On startup it reads the gateway’s OpenAPI contract from /v1/openapi.json and registers one MCP tool per (non-deprecated) endpoint. The tool name is the operation’s operationId in snake_case, and each tool’s input is the endpoint’s path + query + body parameters flattened into a single object. Both the local dev server and the Cloud gateway serve the same OpenAPI contract, so the same tools are available against either — only the configured URL differs. Representative tools (the exact set tracks the gateway’s current API):
ToolBacking endpoint
list_tracesGET /v1/traces
get_traceGET /v1/traces/{traceId}
list_spansGET /v1/spans
get_capabilitiesGET /v1/capabilities
list_sessionsGET /v1/sessions
create_scorePOST /v1/scores
See the API reference for the full list of operations — every one of them is exposed as a tool.

​
Configuration

The server talks to exactly one URL. Set it with AGENTMARK_API_URL.
VariableDefaultDescription
AGENTMARK_API_URLhttps://api.agentmark.coGateway URL — set to http://localhost:9418 for the local dev server
AGENTMARK_API_KEY–API key for authentication (required for Cloud; local dev is unauthenticated)
AGENTMARK_TIMEOUT_MS30000Per-request timeout in milliseconds

​
Editor setup

Run the server with npx — there’s nothing to install. npm create agentmark@latest wires this up for you (as the agentmark and agentmark-local entries); the configs below are the manual equivalent.
Point at your running agentmark dev server. Add to .mcp.json (Claude Code), .cursor/mcp.json (Cursor), or your editor’s MCP config:
{
  "mcpServers": {
    "agentmark-local": {
      "command": "npx",
      "args": ["-y", "@agentmark-ai/mcp-server"],
      "env": {
        "AGENTMARK_API_URL": "http://localhost:9418"
      }
    }
  }
}
Register both entries to work across local and Cloud in one session. MCP clients namespace tools by server name, so your assistant calls agentmark-local/list_traces for local traces and agentmark/list_traces for Cloud.

​
Querying traces

A typical debugging flow: ask your assistant to list recent traces, then drill into one.
  • list_traces accepts the same query parameters as GET /v1/traces — limit, offset, status, user_id, model, session_id, dataset_run_id, name, tag, and date filters. Pagination is offset-based.
  • get_trace takes the traceId path parameter plus an optional fields query value (e.g. fields=graph) and returns the trace with its spans.
Because the tools mirror the REST API one-to-one, the API reference is the source of truth for every tool’s parameters and response shape.

​
Error handling

Tool calls that fail return an MCP error result — { isError: true, content: [{ type: "text", text: "..." }] } — with the underlying HTTP status or message in the text. There is no separate error-code enum to handle.

​
Requirements

For local debugging:
  1. Run npx agentmark dev to start the local dev server (API on port 9418).
  2. Execute prompts to generate traces.
  3. Ask your AI editor to query and debug them via the agentmark-local tools.

​
Programmatic usage

You can run the server from code: 
import { createMCPServer, runServer } from '@agentmark-ai/mcp-server';

// Run with stdio transport (for MCP clients)
await runServer();

// Or create a server instance for a custom transport
const server = await createMCPServer();

​
Related documentation

AI editor integration

The docs MCP for authoring AgentMark files

Traces and logs

Learn about AgentMark tracing

API reference

Every gateway operation, one per MCP tool

​
Have Questions?

We’re here to help! Choose the best way to reach us: