> ## Documentation Index
> Fetch the complete documentation index at: https://mcpjam-docs-uer-50-remove-em-dashes.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`.