Skip to main content
AgentMark ships two MCP servers for AI-powered editors (Claude Code, Cursor, VS Code, Zed), via the Model Context Protocol:
  • Docs MCP (agentmark-docs): a remote server that teaches your editor how to author AgentMark files
  • Trace server (@agentmark-ai/mcp-server, npx binary agentmark-mcp): connects to your gateway (local or Cloud) so your editor can query and debug live data
npm create agentmark@latest wires both into the editors you select.

​
Docs MCP: author files from your editor

The docs MCP (agentmark-docs) lets your editor’s AI query AgentMark documentation, so it can create and update .prompt.mdx files, datasets, and config directly from your AI chat interface. Configuring the AgentMark docs MCP server inside an AI code editor and authoring a .prompt.mdx file The animation shows an AI code editor with the AgentMark docs MCP configured: the user asks the assistant to create a prompt, and the assistant authors a valid .prompt.mdx file using patterns it pulled from the docs MCP.

​
Manual setup

Add the following configuration to your AI code editor settings: 
{
  "mcpServers": {
    "agentmark-docs": {
      "url": "https://docs.agentmark.co/mcp"
    }
  }
}

​
Trace server: query traces and data

The @agentmark-ai/mcp-server package exposes the AgentMark gateway to your editor. 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.

​
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

MCP tools in prompts

Use MCP tools directly within your AgentMark prompts

Tracing setup

Instrument your app to produce the traces these tools query

API reference

Every gateway operation, one per MCP tool

​
Have Questions?

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