Connect to nima's MCP server

nima's MCP server lets an MCP client such as Claude Code or Claude.ai search what nima knows, read signals, beacons and specs, file signals, manage watches and reminders, and, with a headless admin key, start agent operations and manage integrations. This page covers the endpoint, how to connect, the permissions, which tools appear, how a tool call behaves, and how to fix a missing tool.

The nima MCP server endpoint

The nima MCP server lives at https://mcp.getnima.io/mcp. It speaks JSON-RPC 2.0 over Streamable HTTP, is stateless, and answers POST only. It has no sessions and never streams.

The Mcp-Session-Id and MCP-Protocol-Version request headers are ignored.

Connecting an MCP client with OAuth

OAuth is the default way to connect Claude Code and Claude.ai. You copy no client ID or secret: the client registers itself with nima (dynamic client registration), then sends you to a consent screen.

claude mcp add --transport http nima https://mcp.getnima.io/mcp

The consent screen reads "wants to use nima", names the workspace you are signed in to, and lists the permissions. Click Allow to grant them, or Cancel to stop. Cancel sends the client back with the OAuth error access_denied. The same commands appear in Connect a coding agent, with the rest of the setup for coding agents.

MCP permissions on the consent screen

The nima consent screen asks for eight permissions, each backed by one OAuth scope. They sit under a What it can do toggle, read permissions first, then the two write permissions, which are marked Edits.

The token can be narrower than the screen. If your role cannot back a permission, such as a member approving sources:read, nima drops that scope from the token. If none remain, the approval fails with User lacks permissions to grant the requested scopes. Effective access is always your live role in the workspace combined with the scopes, so a token loses access the moment you leave the workspace.

An access token lasts 1 hour. The client refreshes it with a refresh token that lasts 30 days, rolling: every refresh starts a new 30-day window, and a connector you stop using lapses after 30 days. Every refresh re-checks that you are still an active member. The full flow is on OAuth for MCP clients, and every scope is listed on API scopes.

Connecting with an API key instead of OAuth

An API key connects a client that has no browser, such as a CI job or a script. Create one under Settings, then API keys, in the nima admin panel, and send it as a bearer token.

claude mcp add --transport http nima https://mcp.getnima.io/mcp \
  --header "Authorization: Bearer nima_…"

A key acts as you, in the workspace where you created it, with only the scopes you ticked. The Settings form offers 13 consumer scopes: the 8 consent-screen scopes plus documents:write, versions:read, versions:write, prd:read and prd:write. Keys expire after 30, 90 or 365 days (default 90), can be limited to IP ranges, and are shown once. For MCP, tick at least one of the eight consent-screen scopes; the other five only matter for direct API calls. As on the consent screen, a scope your role cannot back (a member ticking sources:read) is dropped from the key. See API authentication for rotation, revocation and the 10-key limit.

A key from Settings never carries the admin scopes that unlock operations and integrations tools. Those come from Slack, as the next section explains.

Headless admin keys for operations and integrations tools

Agent operations and integration administration are not part of the OAuth consent screen. A workspace owner or admin mints a separate 30-day key for each from Slack, and connects the client with that key as the bearer token.

The two keys are separate on purpose: the operations key does not administer integrations, and the integrations key cannot read signals, specs or the knowledge graph. Connect one MCP entry per key if you need both.

To mint a key:

1. In Slack, run /nima mcp-key operations or /nima mcp-key integrations. You can also write @nima mcp-key operations in a channel or DM.
2. Click Confirm on the message nima replies with, or write @nima confirm <code> with the code it shows, in the same channel within 5 minutes.
3. Copy the key from the ephemeral message. It is shown once.

Only a linked nima owner or admin can run these commands. /nima mcp-key list shows your keys that have not been revoked, with their scopes and expiry dates, and /nima mcp-key revoke <key-id> revokes one. Slack-minted keys count toward the limit of 10 active keys per user per workspace.

Without the right key, a call to one of these tools returns this text as a tool error:

This tool requires an explicit headless grant. Ask a workspace admin to use /nima mcp-key operations or /nima mcp-key integrations in Slack, then connect using that key. Existing OAuth consent does not grant administration.

Which MCP tools you will see

A default OAuth connection lists 30 tools. nima registers 56 in total; the rest need a headless key, and 3 are reserved for hosted agent runs.

• Consent-scope tools always appear. tools/list shows every tool behind one of the eight consent scopes, even if your token lacks that scope. Calling it then answers 403 insufficient_scope, which makes the client ask you to consent again. That is how a token issued before a new scope existed learns about new tools.
• Headless tools appear only when the token holds the scope. Operations tools need operations:write, integration admin tools need integrations:write, and the approval and identity tools need actions:approve or identities:write. Slack mints only the first two. Nobody can mint actions:approve or identities:write today, so approve_action, get_action, list_pending_actions, discard_action and link_my_identity are not reachable with a key or an OAuth client. Approvals happen on the Slack card.
• Hosted-run tools never appear. get_run_brief, report_or_ask_pm and wait_for_checks belong to agent runs on nima's hosted machines and are hidden from everyone else.

Each tool is documented on exactly one page.

The five operation read tools (get_operation, get_operation_result, list_operations, get_operation_brief, inspect_operation) sit behind documents:read, so they are part of the default 30.

How MCP tool calls behave

Every tool call is an HTTP request from the MCP server back to the nima API, carrying your bearer token. Guards, scopes, throttling and workspace scoping therefore apply exactly as they do for a direct API call.

• Timeout. A call fails after 60 seconds.
• Invalid input. Arguments are validated strictly and unknown keys are rejected. A failure returns a normal result with isError: true and text starting Invalid arguments:, not a protocol error. An unknown tool name returns JSON-RPC error -32602.
• Server errors. A 5xx or a network failure returns isError text of the form <status> followed by a pointer to the server logs. Other non-2xx responses return the status and the first 500 characters of the response body.
• Rate limits. A tool call spends the MCP endpoint's default limit and then the limit of the route behind the tool, so about 100 calls per minute per address is the practical ceiling. A limited inner call returns isError text starting 429 {. See API rate limits.
• Missing scope. A consent-scope tool without the scope answers 403 insufficient_scope with a WWW-Authenticate challenge. A headless tool returns the headless-grant text quoted above.
• Summaries. search_signals, list_beacons and list_specs return trimmed summaries with a fixed field list. Use get_signal, get_beacon or get_document_markdown for the full record.
• Origin. A request that carries an Origin header must come from an allowed origin, otherwise it gets 403 Origin not allowed. Real MCP clients send no Origin, so this only blocks browser pages.

Troubleshooting a missing or failing nima tool

Most tool problems come from the wrong workspace, a missing scope, or a role that cannot back the scope. Work through these causes in order.

• Connected to the wrong workspace. Switch workspaces in the nima admin panel, then disconnect and reconnect the connector. The consent screen has no workspace switcher.
• A consent-scope tool answers insufficient_scope. The token was issued without that permission. Disconnect and reconnect, and allow the permission on the consent screen.
• An operations or integrations tool is missing. It needs a headless key. Ask a workspace owner or admin to run /nima mcp-key operations or /nima mcp-key integrations in Slack, and connect with that key.
• get_signal_source is missing or refused. sources:read can only be granted by a workspace owner or admin. A member's token drops it.
• A tool answers 403 INSUFFICIENT_PERMISSIONS with details.feature. The tool's route is declared under a plan feature (for example code_intelligence for search_code, blast_radius and get_data_model) that the workspace plan may lack. Handle the error and ask the nima team.
• A watch tool works but nothing fires. Watches and outbound actions each need a workspace setting turned on. See Availability.
• Every call fails with 401. The access token expired or the refresh token lapsed after 30 days. Reconnect. An API key fails the same way once it expires.
• Disconnecting. In Claude Code, run claude mcp remove nima. In Claude.ai, remove the connector under Settings, then Connectors. Revoke an API key under Settings, then API keys, and a Slack-minted key with /nima mcp-key revoke <key-id>.