> ## Documentation Index
> Fetch the complete documentation index at: https://puzzlet-9ba7bb98.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Gateway MCP
> Wire the AgentMark gateway MCP server (agentmark-mcp) into your AI editor to drive the full AgentMark API: traces, spans, scores, apps, environments, and alerts.
The AgentMark **gateway MCP** (`@agentmark-ai/mcp-server`, `npx` binary `agentmark-mcp`) exposes your gateway to your AI editor over the [Model Context Protocol](https://modelcontextprotocol.io). 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, write scores, provision apps, manage environments, configure alerts. It's one of several ways to [connect a coding agent to AgentMark](/coding-agents/overview); for documentation lookups while authoring, pair it with the [docs MCP](/coding-agents/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` |
| `create_app` | `POST /v1/apps` |
| `create_alert` | `POST /v1/alerts` |
See the [API reference](/api-reference/overview) 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.
Point at your running `agentmark dev` server. Add to `.mcp.json` (Claude Code), `.cursor/mcp.json` (Cursor), or your editor's MCP config:
```json theme={null}
{
"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):
```json theme={null}
{
"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](/api-reference/overview) 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 `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:
```typescript theme={null}
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
How the skill, docs MCP, and gateway MCP fit together
Let your editor author files from the live docs
Use MCP tools directly within your AgentMark prompts
Every gateway operation, one per MCP tool
Have questions?
Reach out any time: