MCPJam as an MCP Server

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.

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

Claude Desktop
Claude Code
Cursor
Other clients

Add to claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "mcpjam": {
      "command": "npx",
      "args": ["-y", "@mcpjam/cli@latest", "mcp"]
    }
  }
}

claude mcp add mcpjam -- npx -y @mcpjam/cli@latest mcp

Add to .cursor/mcp.json in your project (or ~/.cursor/mcp.json):

{
  "mcpServers": {
    "mcpjam": {
      "command": "npx",
      "args": ["-y", "@mcpjam/cli@latest", "mcp"]
    }
  }
}

Any client that supports stdio servers can launch:

npx -y @mcpjam/cli@latest mcp

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

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`
`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:

connect_server with { "name": "dev", "command": "node", "args": ["dist/server.js"] }
list_tools with { "server": "dev" } — review names, descriptions, schemas
call_tool with { "server": "dev", "tool": "search", "arguments": { "query": "test" } }
get_notifications with { "server": "dev" } — did the server log what you expected? Did it emit notifications/tools/list_changed?
Iterate on the server code, then disconnect_server / connect_server to pick up the rebuild
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.

Guides

Reference

Why use this instead of the CLI?

Setup

Tools

Connections

Exercising the target

Stateless diagnostics

Example session

Relationship to the hosted MCP server

Troubleshooting

​Why use this instead of the CLI?

​Setup

​Tools

​Connections

​Exercising the target

​Stateless diagnostics

​Example session

​Relationship to the hosted MCP server

​Troubleshooting

Why use this instead of the CLI?

Setup

Tools

Connections

Exercising the target

Stateless diagnostics

Example session

Relationship to the hosted MCP server

Troubleshooting