Gateway MCP - AgentMark Docs

The AgentMark gateway MCP (@agentmark-ai/mcp-server, npx binary agentmark-mcp) exposes your gateway to your AI editor over the Model Context Protocol. 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. It’s one of several ways to connect a coding agent to AgentMark; for documentation lookups while authoring, pair it with the docs MCP.

How AgentMark generates tools

The server doesn’t 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 local server does implement the trace and span reads that local debugging relies on. Representative tools (the exact set tracks the gateway’s current API):

Tool	Backing endpoint
`list_traces`	`GET /v1/traces`
`get_trace`	`GET /v1/traces/{traceId}`
`list_sessions`	`GET /v1/sessions`
`create_score`	`POST /v1/scores`
`append_dataset_row`	`POST /v1/datasets/{datasetName}/rows`
`list_experiments`	`GET /v1/experiments`
`create_app`	`POST /v1/apps`
`list_deployments`	`GET /v1/deployments`
`create_alert`	`POST /v1/alerts`

See the API reference for the full list of operations. The server exposes every one of them as a tool.

Configuration

The server talks to exactly one URL. Set it with AGENTMARK_API_URL.

Variable	Default	Description
`AGENTMARK_API_URL`	`https://api.agentmark.co`	Gateway 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 needs no authentication)
`AGENTMARK_TIMEOUT_MS`	`30000`	Per-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.

Local dev server
AgentMark Cloud

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"
      }
    }
  }
}

Point at the Cloud gateway. After agentmark login, you need no key: the server resolves your session from ~/.agentmark/auth.json and refreshes it automatically. For CI or agents without a login session, supply an API key (it takes precedence over the session):

{
  "mcpServers": {
    "agentmark": {
      "command": "npx",
      "args": ["-y", "@agentmark-ai/mcp-server"],
      "env": {
        "AGENTMARK_API_KEY": "your-api-key"
      }
    }
  }
}

AGENTMARK_API_URL defaults to https://api.agentmark.co, so you only need to set it for staging or self-hosted gateways.

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 (for example, 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:

Run agentmark dev to start the local dev server (API on port 9418).
Execute prompts to generate traces.
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();

Coding agents

How the skill, docs MCP, and gateway MCP fit together

Docs MCP

Let your editor author files from the live docs

MCP tools in prompts

Use MCP tools directly within your AgentMark prompts

API reference

Every gateway operation, one per MCP tool

Have questions?

Reach out any time:

Email the team at hello@agentmark.co for support
Schedule an Enterprise Demo to learn about AgentMark’s business solutions

​How AgentMark generates tools

​Configuration

​Editor setup

​Example: querying traces

​Error handling

​Requirements

​Programmatic usage

​Related documentation

Coding agents

Docs MCP

MCP tools in prompts

API reference

​Have questions?

How AgentMark generates tools

Configuration

Editor setup

Example: querying traces

Error handling

Requirements

Programmatic usage

Related documentation

Have questions?