> ## Documentation Index
> Fetch the complete documentation index at: https://mcpjam-mintlify-docs-update-pr-2772-1782277917413.mintlify.site/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={null}
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

<Tabs>
  <Tab title="Claude Desktop">
    Add to `claude_desktop_config.json` (Settings → Developer → Edit Config):

    ```json theme={null}
    {
      "mcpServers": {
        "mcpjam": {
          "command": "npx",
          "args": ["-y", "@mcpjam/cli@latest", "mcp"]
        }
      }
    }
    ```
  </Tab>

  <Tab title="Claude Code">
    ```bash theme={null}
    claude mcp add mcpjam -- npx -y @mcpjam/cli@latest mcp
    ```
  </Tab>

  <Tab title="Cursor">
    Add to `.cursor/mcp.json` in your project (or `~/.cursor/mcp.json`):

    ```json theme={null}
    {
      "mcpServers": {
        "mcpjam": {
          "command": "npx",
          "args": ["-y", "@mcpjam/cli@latest", "mcp"]
        }
      }
    }
    ```
  </Tab>

  <Tab title="Other clients">
    Any client that supports stdio servers can launch:

    ```bash theme={null}
    npx -y @mcpjam/cli@latest mcp
    ```

    With a global install (`npm i -g @mcpjam/cli`), use `mcpjam mcp` as the command instead.
  </Tab>
</Tabs>

<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`).
</Note>

## 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`](/cli/server-inspection) |
| `probe_server`  | HTTP-only probe: transport selection, auth requirements, OAuth metadata discovery — same as `mcpjam server probe`  |

## 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` (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                          |

## Troubleshooting

* **Client says the server failed to start** — run `npx -y @mcpjam/cli@latest mcp` in a terminal; you should see `MCPJam 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`.