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.

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

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

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

Claude Code

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

Cursor

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

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

Other clients

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:

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.