> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mcpjam.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCPJam as an MCP Server

> Run MCPJam as a local stdio MCP server so agents can connect to, exercise, and debug other MCP servers

`mcpjam mcp` runs MCPJam itself as an MCP server over stdio. Add it to any MCP client (Claude Desktop, Claude Code, Cursor, or your own agent) and the agent gets MCPJam's local testing engine as tools: connect to a server under test, call its tools, read its resources and prompts, watch the notifications it emits, and run diagnostic sweeps.

```bash theme={"theme":"css-variables"}
npx -y @mcpjam/cli@latest mcp
```

Everything runs locally in the spawned process. No account, login, or hosted backend is involved, and the server under test can be a local stdio process, something hosted tooling can't reach.

## Why use this instead of the CLI?

Agents with shell access can already run `mcpjam` commands directly, and for one-shot checks that is often the better choice. The MCP server mode adds two things the CLI cannot do:

* **Clients without a shell.** Claude Desktop and other chat-style MCP clients can't run CLI commands. This is the only way to give them MCPJam's testing engine.
* **Persistent sessions.** Each CLI invocation reconnects to the target server. `mcpjam mcp` holds connections open across tool calls, so the agent can observe `notifications/message` logs, `list_changed` events, resource updates, and other session behavior that one-shot commands miss.

## Setup

> [tab] Claude Desktop
>
> Add to `claude_desktop_config.json` (Settings → Developer → Edit Config):
>
> ```json theme={"theme":"css-variables"}
> {
>   "mcpServers": {
>     "mcpjam": {
>       "command": "npx",
>       "args": ["-y", "@mcpjam/cli@latest", "mcp"]
>     }
>   }
> }
> ```

> [tab] Claude Code
>
> ```bash theme={"theme":"css-variables"}
> claude mcp add mcpjam -- npx -y @mcpjam/cli@latest mcp
> ```

> [tab] Cursor
>
> Add to `.cursor/mcp.json` in your project (or `~/.cursor/mcp.json`):
>
> ```json theme={"theme":"css-variables"}
> {
>   "mcpServers": {
>     "mcpjam": {
>       "command": "npx",
>       "args": ["-y", "@mcpjam/cli@latest", "mcp"]
>     }
>   }
> }
> ```

> [tab] Other clients
>
> Any client that supports stdio servers can launch:
>
> ```bash theme={"theme":"css-variables"}
> npx -y @mcpjam/cli@latest mcp
> ```
>
> With a global install (`npm i -g @mcpjam/cli`), use `mcpjam mcp` as the command instead.

> [!NOTE]
>
> In MCP server mode all status output goes to stderr; stdout carries only
> JSON-RPC. The `--timeout <ms>` global flag sets the default per-request
> timeout against target servers (individual tool calls can override it with
> `timeoutMs`).

## Tools

### Connections

| Tool | Description |
| - | - |
| `connect_server` | Open a persistent connection to a target server: `url` (+ optional `accessToken`, `headers`) for HTTP, or `command` (+ optional `args`, `env`, `cwd`) for stdio. Returns the negotiated initialization info. |
| `disconnect_server` | Close a connection and discard its buffered notifications |
| `list_servers` | List open connections with status and a redacted target summary |
| `server_info` | Initialization info for a connection: protocol version, transport, server version, capabilities, instructions |
| `ping_server` | MCP ping with round-trip latency |

### Exercising the target

| Tool | Description |
| - | - |
| `list_tools` | List the target's tools (with pagination cursor) |
| `call_tool` | Call a tool and return the target's raw `CallToolResult`: check the payload's `isError` for tool-level failures |
| `list_resources` | List resources, or resource templates with `templates: true` |
| `read_resource` | Read a resource by URI |
| `list_prompts` | List prompts |
| `get_prompt` | Fetch a named prompt with optional string arguments |
| `get_notifications` | Notifications buffered since connect: log messages, progress, `list_changed` events, resource updates. Filter by `server`/`method`, optionally `clear` |

### Stateless diagnostics

| Tool | Description |
| - | - |
| `server_doctor` | One-shot diagnostic sweep (HTTP or stdio target): same checks as [`mcpjam server doctor`](https://docs.mcpjam.com/cli/server-inspection) |
| `probe_server` | HTTP-only probe: transport selection, auth requirements, OAuth metadata discovery: same as `mcpjam server probe` |

## Skills over MCP

Alongside its tools, `mcpjam mcp` serves two of MCPJam's Agent Skills over the [`io.modelcontextprotocol/skills` extension](https://github.com/modelcontextprotocol/ext-skills/blob/main/specification/stable/skills.mdx) (SEP-2640):

| Skill | What it is for |
| - | - |
| `mcp-inspector` | Interpreting probe, doctor, OAuth, and conformance output conservatively: the tools this server exposes |
| `mcpjam-eval-import` | Converting an existing test corpus into an MCPJam eval suite |

A client that advertises the extension sees them in `skills/list` and can load them with no install step; you do not need `npx skills add` for these two when you are connected this way. Each skill's files are also readable as ordinary resources under `skill://mcpjam/<name>/…`, so `resources/list` returns rows for them.

Every file carries a SHA-256 digest and a byte size, and a conforming host verifies both before loading. The listing and each `skills/get` result carry `ttlMs: 0`, which the protocol defines as immediately stale, because the files behind `npx -y @mcpjam/cli@latest mcp` change with every release.

`mcpjam-eval-import` is served by the [hosted MCP server](https://docs.mcpjam.com/cli/mcp-server.md#relationship-to-the-hosted-mcp-server) too, under the same URI. If you are connected to both at once, address it by server (`<server>/mcpjam-eval-import`) rather than by bare URI.

## Example session

A typical agent flow while developing a stdio server:

1. `connect_server` with `{ "name": "dev", "command": "node", "args": ["dist/server.js"] }`
2. `list_tools` with `{ "server": "dev" }`; review names, descriptions, schemas
3. `call_tool` with `{ "server": "dev", "tool": "search", "arguments": { "query": "test" } }`
4. `get_notifications` with `{ "server": "dev" }`: did the server log what you expected? Did it emit `notifications/tools/list_changed`?
5. Iterate on the server code, then `disconnect_server` / `connect_server` to pick up the rebuild
6. `server_doctor` with the same `command` for a final health sweep

Tool results are JSON payloads describing the target server. Errors come back as structured `{ "error": { "code", "message" } }` payloads with `isError: true`, for example `USAGE_ERROR` for invalid input or `SERVER_UNREACHABLE` when the target is down.

## Relationship to the hosted MCP server

MCPJam also operates a hosted MCP server at `mcp.mcpjam.com/mcp` that exposes your MCPJam **account** (projects, saved servers, eval suites and runs) behind OAuth. The two are complementary. `mcpjam mcp` protocol `serverInfo.name` is `mcpjam`; its title is `MCPJam CLI`. The hosted server identifies as `MCPJam MCP`.

| | `mcpjam mcp` (this page) | `mcp.mcpjam.com` |
| - | - | - |
| Runs | Locally, spawned by your MCP client | Hosted |
| Auth | None | MCPJam account (OAuth) |
| Scope | Test any server reachable from your machine, including local stdio | Servers and evals saved in your projects |
| Transport to MCPJam | stdio | Streamable HTTP |
| Protocol name | `mcpjam` | `MCPJam MCP` |
| Title | `MCPJam CLI` | `MCPJam MCP` |

## Troubleshooting

* **Client says the server failed to start**: run `npx -y @mcpjam/cli@latest mcp` in a terminal; you should see `MCPJam CLI MCP server listening on stdio` on stderr. First runs may be slow while `npx` downloads the package; pre-install with `npm i -g @mcpjam/cli` and use `mcpjam mcp` to avoid the download.
* **`connect_server` fails with `SERVER_UNREACHABLE`**: the target URL or command is wrong, or the target crashed on startup. Try `server_doctor` against the same target for a structured diagnosis.
* **A connection name is already taken**: `connect_server` refuses to overwrite an existing name; `disconnect_server` it first or pass a different `name`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.