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
  • Gateway MCP (@agentmark-ai/mcp-server, npx binary agentmark-mcp): connects to your gateway (local or Cloud) and exposes the entire API surface: traces and spans, but also datasets, scores, experiments, apps, deployments, environments, alerts, and annotation queues
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"
    }
  }
}

​
Gateway MCP: drive the full API from your editor

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 call any gateway operation without leaving your editor: list traces and drill into spans, append dataset rows, write scores, provision apps, manage deployments and environments, configure alerts and annotation queues. Despite the trace-heavy examples below, it is not a trace-only server; it is the programmatic surface for everything the Dashboard does.

​
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 register against either; only the configured URL differs. Operations the local server doesn’t implement (for example create_app) return a 404 at call time; the trace and span reads that local debugging relies on are implemented. Representative tools (the exact set tracks the gateway’s current API):
ToolBacking endpoint
list_tracesGET /v1/traces
get_traceGET /v1/traces/{traceId}
list_sessionsGET /v1/sessions
create_scorePOST /v1/scores
append_dataset_rowPOST /v1/datasets/{datasetName}/rows
list_experimentsGET /v1/experiments
create_appPOST /v1/apps
list_deploymentsGET /v1/deployments
create_alertPOST /v1/alerts
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 Cloud authentication (optional after agentmark login; required in CI or agents without a login session; 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 gateway entries (agentmark and agentmark-local) 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.

​
Example: 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-ai/cli 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?

Reach out any time: