Tools, Resources & Prompts

List, read, and call MCP server tools, resources, and prompts

Once connected (with or without auth), the tools, resources, and prompts command groups let you explore and exercise what the server exposes.

Running commands as a host

Add --host <id> to any tools, resources, or prompts command to connect the way a real host would — sending that host’s clientInfo, advertised clientCapabilities, and protocol version in the MCP initialize handshake, exactly as the Inspector Playground does.

mcpjam tools list --url https://your-server.com/mcp --host claude

Valid host IDs match the presets in the Inspector: claude, chatgpt, cursor, copilot, codex, mcpjam.

Tool visibility with --host: tools list --host hides tools whose _meta.ui.visibility is ["app"] — those are app-only tools the host’s model cannot see. The output includes a host field and a toolsDroppedVisibility count. Hosts that opt out of visibility filtering (such as cursor) keep all tools. tools call --host rejects app-only tools with a usage error; omit --host to call them as an operator.

Conflict with --client-capabilities: --host and --client-capabilities both set the exact advertised capabilities and cannot be combined. The CLI exits with a usage error if both are passed.

Interactive multi-round-trip (input_required)

Add --interactive to tools call, prompts get, or resources read to handle servers that return an input_required result. When the server embeds an elicitation request, the CLI renders it to the terminal and collects your response from stdin, then retries the original operation — repeating for as many rounds as the server needs.

mcpjam tools call --url https://your-server.com/mcp \
  --tool-name book_flight \
  --tool-args '{}' \
  --interactive

How prompts appear: The server’s message is printed to stderr, followed by a consent prompt ([a]ccept / [d]ecline / [c]ancel). For form fields, each field is prompted in turn with its type shown in brackets. For URL-mode elicitations, the URL is printed as plain text and you are asked for consent — the CLI never opens a browser automatically.

Non-interactive fallback (--yes): Pass --yes alongside --interactive to decline every embedded input request without prompting. This is also the automatic behavior when stdin is not a TTY or the CI environment variable is set — the CLI declines cleanly rather than blocking.

Stdin conflict: --interactive reads answers from stdin, so it cannot be combined with --tool-args -, --tool-args-stdin, or --prompt-args -. Pass arguments as inline JSON or @path instead.

Capability advertisement: --interactive advertises elicitation: { form, url } in the MCP initialize handshake. If you also pass --client-capabilities or --host and that exact set omits elicitation, the CLI exits with a usage error — add "elicitation": { "form": {}, "url": {} } to the pinned set or drop --interactive.

Tools

List tools

mcpjam tools list --url https://your-server.com/mcp --access-token $TOKEN

Returns every tool the server exposes, including names, descriptions, and input schemas.

Call a tool

mcpjam tools call --url https://your-server.com/mcp --access-token $TOKEN \
  --tool-name search_docs \
  --tool-args @params.json --quiet --format json

Tool arguments can be inline JSON, @path, - for stdin, or --tool-args-stdin as a shorthand for stdin. The result includes the tool’s response content.

tools call supports --debug-out <path> to capture the full request/response trace for debugging. For stdio targets, the artifact records only the explicit env keys passed through -e/--env; inherited shell variables are not enumerated.

Calling as a less-capable client

Real MCP clients differ from each other, and from the spec. Two flags let you call a server as one of those clients, without authoring a host first — the same behaviors a --host carries via its mcpProfile:

# Read only the first page of tools/list, like the hosts that never follow
# nextCursor. Tools past page one are invisible to the call.
mcpjam tools list --url https://your-server.com/mcp --first-page-only

# Call as a client that never implemented MRTR. On 2026-07-28 this stops
# advertising `elicitation`, so a server that would have elicited answers
# -32021 instead of starting a round.
mcpjam tools call --url https://your-server.com/mcp \
  --tool-name confirm_delete --tool-args '{"id":"42"}' --no-mrtr

Unlike the header flags below, neither is HTTP-only — pagination truncation and the MRTR knob both work over stdio, so they mean the same thing with --command.

--first-page-only has a second-order effect worth knowing on 2026-07-28: the SEP-2243 mirroring source is the aggregated tool list the client cached, so a tool from page two is called with no Mcp-Param-* headers and a strict server answers -32020. That is not a bug in the flag — it is exactly how a real first-page-only client fails, and it is often the reason a tool “works in the inspector but not in that host”.

Debugging Mcp-Param-* headers (SEP-2243)

On a 2026-07-28 HTTP connection, a tool argument annotated with x-mcp-header is mirrored into an Mcp-Param-{Name} request header, and a conforming server cross-checks the two. Two flags let you exercise the failure paths on purpose:

# Call as a client that has NOT implemented the mirroring. A conforming server
# should answer -32020 HeaderMismatch; the CLI surfaces that as-is.
mcpjam tools call --url https://your-server.com/mcp   --tool-name execute_sql --tool-args '{"region":"us-east"}'   --no-param-headers

# Send a deliberately WRONG value, reproducing a header/body mismatch exactly.
mcpjam tools call --url https://your-server.com/mcp   --tool-name execute_sql --tool-args '{"region":"us-east"}'   --mcp-header Mcp-Param-Region=eu-west

--mcp-header uses Name=Value (not --header’s Key: Value) because a mirrored value routinely contains :. Repeat it for several headers; the last occurrence of a name wins.

Supplying any Mcp-Param-* header turns the automatic mirroring off for that call, so the headers you pass are the only Mcp-Param-* ones sent. This is not a convenience — it is what makes the override work at all: the MCP client merges the mirrored values over caller-supplied headers, so with mirroring left on your deliberately wrong value would be silently replaced by the correct one and no -32020 would ever occur. Headers outside the Mcp-Param-* family (Mcp-Method, Mcp-Name, …) are unaffected and do not change mirroring.

When either flag is in play — or with --rpc — the CLI prints the headers that actually went out to stderr, including on the failure path, so stdout stays a clean machine-readable result:

Mcp-Param-*: Mcp-Param-Region=us-east

Both flags are HTTP-only: SEP-2243 mirroring is a Streamable HTTP concern, so using them with --command is a usage error rather than a silent no-op.

Render a tool result in Inspector

If tools list shows _meta.ui.resourceUri, deprecated _meta["ui/resourceUri"], or openai/outputTemplate in toolsMetadata, the tool has interactive UI. Add --ui to execute it once and render the completed result in Inspector’s Playground:

mcpjam tools call --url https://your-server.com/mcp --access-token $TOKEN \
  --tool-name create_view \
  --tool-args @params.json \
  --ui \
  --quiet --format json

Without --ui, tools call returns the raw tool result. With --ui, it opens Inspector by default in a TTY and returns an envelope containing the raw result, inspectorBrowserUrl, and compact inspectorRender evidence. inspectorRender.status is the UI signal: rendered means Inspector accepted the render, skipped means the tool succeeded but the active browser client, a render precondition, or the render wait was missing, and error means a non-recoverable Inspector render command failed. inspectorRender.remediation is always present and is one of open_browser, retry, reconnect_server, or none. Skipped renders emit a stable root warning plus inspectorRender.warning with code, message, remediation, and optional browserUrl, hasActiveClient, and inspectorStarted fields. Stable skipped-render codes are no_active_client, timeout, disconnected_server, and unsupported_in_mode. Pass --require-render when a skipped render should become a hard error instead of a warning. Browser automation can open inspectorBrowserUrl itself and pass --no-open; --inspector-url is the local Inspector backend/API base URL. If you already know the Inspector browser/client URL, pass --frontend-url <url> to use it directly and skip health-advertised frontend checks and local dev port discovery.

For agent/browser automation, either let --ui open Inspector automatically in a TTY, or open http://127.0.0.1:6274/#playground in the automation browser first and run tools call --ui --no-open --quiet --format json. Add --attach-only when startup, browser opening, and discovery should be disallowed. Agents should confirm inspectorRender.status === "rendered" before assuming the UI is visible, and use inspectorRender.remediation to recover from skipped renders. Default non-TTY --ui runs do not open a browser unless --open is passed. TTY stderr runs print the Playground URL and initial wait message unless --quiet is set; the elapsed-seconds heartbeat only appears when stderr is a TTY. The normal JSON output is compact; pass --debug-out <path> for the full render envelope.

For a local stdio server:

mcpjam tools list \
  --command npx \
  --args -y @modelcontextprotocol/server-everything \
  --cwd $PWD \
  -e DEBUG=1

Resources

List resources

mcpjam resources list --url https://your-server.com/mcp --access-token $TOKEN

Read a resource

mcpjam resources read --url https://your-server.com/mcp --access-token $TOKEN \
  --resource-uri "file:///docs/readme.md"

Use resources read --resource-uri ui://... when you need to inspect raw widget HTML or other UI resources directly.

List resource templates

mcpjam resources templates --url https://your-server.com/mcp --access-token $TOKEN

Prompts

List prompts

mcpjam prompts list --url https://your-server.com/mcp --access-token $TOKEN

Get a prompt

mcpjam prompts get --url https://your-server.com/mcp --access-token $TOKEN \
  --prompt-name summarize \
  --prompt-args '{"text": "Hello world"}'

Common patterns

Enumerate the full server surface

# One-shot: doctor already sweeps everything
mcpjam server doctor --url https://your-server.com/mcp --access-token $TOKEN

# Or individually for focused output
mcpjam tools list --url $URL --access-token $TOKEN --format json | jq '.tools[].name'
mcpjam resources list --url $URL --access-token $TOKEN --format json | jq '.resources[].uri'
mcpjam prompts list --url $URL --access-token $TOKEN --format json | jq '.prompts[].name'

Test a specific tool end-to-end

# List to find the tool
mcpjam tools list --url $URL --access-token $TOKEN --format json \
  | jq '.tools[] | select(.name == "search_docs")'

# Call it
mcpjam tools call --url $URL --access-token $TOKEN \
  --tool-name search_docs \
  --tool-args @params.json \
  --quiet \
  --format json

For generated payloads, pipe JSON through stdin:

echo '{"query":"setup guide"}' | mcpjam tools call --url $URL --access-token $TOKEN \
  --tool-name search_docs --tool-args - --quiet --format json

--tool-args-stdin is equivalent to --tool-args - and cannot be combined with --tool-args or --params in the same command:

generate-params | mcpjam tools call --url $URL --access-token $TOKEN \
  --tool-name search_docs --tool-args-stdin --quiet --format json

Using a credentials file

Instead of passing --access-token to every command, save credentials once and reuse the file:

# Login and save
mcpjam oauth login --url https://your-server.com/mcp --credentials-out creds.json

# Reuse everywhere
mcpjam tools list --url https://your-server.com/mcp --credentials-file creds.json
mcpjam resources list --url https://your-server.com/mcp --credentials-file creds.json
mcpjam tools call --url https://your-server.com/mcp --credentials-file creds.json \
  --tool-name search_docs --tool-args @params.json --quiet --format json

No-auth servers

For servers that don’t require authentication (like mcp.excalidraw.com/mcp), omit the auth flags:

mcpjam tools list --url https://mcp.excalidraw.com/mcp
mcpjam tools call --url https://mcp.excalidraw.com/mcp \
  --tool-name read_me

Stdio child processes inherit the parent shell environment by default. Use -e/--env to add values or override inherited ones for local subprocesses.