Connect a coding agent

nima runs a remote MCP server at https://mcp.getnima.io/mcp. Connecting a coding agent to it lets the agent ask nima why something was built, who asked for it, where the code lives and what a change touches, without leaving its own session. This page is the canonical home for client install commands. The tools themselves are listed on MCP server.

Connect Claude Code to nima

The recommended route for Claude Code is the nima plugin, which bundles the MCP connection, the nima skill and automatic, guarded filing of product-gap signals (on by default; see modes); install it from Install the nima plugin for Claude Code. To connect without the plugin, run claude mcp add --transport http nima https://mcp.getnima.io/mcp to register nima in Claude Code, then run /mcp inside Claude Code, sign in, and click Allow on nima's consent screen.

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

The consent screen names the workspace and the permissions you are granting. There is no client id or secret to copy: nima registers the client for you.

To connect without a browser (CI, a remote box), create a personal API key under Settings > API keys in the nima web app and pass it as a bearer header:

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

Your shell expands $NIMA_API_KEY when you run the command, so Claude Code saves the key text itself in ~/.claude.json. If you do not want the secret on disk, put the server in a project .mcp.json instead and reference the variable, which Claude Code expands at startup:

{
  "mcpServers": {
    "nima": {
      "type": "http",
      "url": "https://mcp.getnima.io/mcp",
      "headers": { "Authorization": "Bearer ${NIMA_API_KEY}" }
    }
  }
}

A key acts as you, in one workspace, with the scopes you ticked. Create one on Authentication; scopes are on Scopes.

Connect Codex to nima

Run codex mcp add nima --url https://mcp.getnima.io/mcp and then codex mcp login nima to register nima in Codex and sign in over OAuth.

codex mcp add nima --url https://mcp.getnima.io/mcp
codex mcp login nima

codex mcp list shows nima as enabled with OAuth once it worked. For a headless machine, add the server to ~/.codex/config.toml and read the key from an environment variable:

[mcp_servers.nima]
url = "https://mcp.getnima.io/mcp"
bearer_token_env_var = "NIMA_API_KEY"

Connect Claude.ai or Claude Desktop to nima

In Claude.ai or Claude Desktop, open Settings > Connectors > Add custom connector, paste https://mcp.getnima.io/mcp as the URL, leave the client id and client secret fields blank, click Connect, then click Allow on nima's consent screen.

Cursor, VS Code and other MCP clients are not tested. Any client that speaks Streamable HTTP and either follows OAuth discovery or lets you set an Authorization: Bearer header should work. nima's server is stateless: it answers POST only, does not use sessions and rejects JSON-RPC batches.

Install the nima skill

The nima skill teaches a coding agent when to call nima's tools: any question about people, requests, decisions or product history, before it concludes that nobody asked for something. In Claude Code, install the nima plugin, which includes the skill. For Codex and other agents, install it with npx skills add getnima/skills, choosing the agent with --agent.

# Codex
npx skills add getnima/skills --agent codex

# Claude Code without the plugin
npx skills add getnima/skills --agent claude-code

Do not install both the plugin and the skill in Claude Code: the plugin already carries the nima skill, and npx skills add would add a duplicate. npx skills installs only the read skill; the filing skill belongs to the plugin because it depends on the plugin's guard. With the npx route, Claude Code exposes the skill as /nima (the plugin's copy is /nima:nima) and Codex as $nima; both also load it on their own when a task matches. The skill is a set of instructions, not a credential: it does nothing until the MCP connection above exists. Source and updates live in the getnima/skills repository on GitHub.

Which nima tool a coding agent should call first

A coding agent connected to nima should pick the tool by the kind of question, and should treat an empty answer as a gap in what nima knows, not as proof that nothing exists.

search_code, blast_radius and get_data_model are declared under the Code Intelligence plan feature. A workspace whose plan lacks it can get a 403 with INSUFFICIENT_PERMISSIONS and details.feature set to code_intelligence; handle it and fall back to the working tree. All three also need GitHub connected so that nima has indexed the repository. Each tool is documented once, with its parameters, on Knowledge tools and Pipeline tools. How the graph is built is on Knowledge graph. For watches and one-time reminders see watch tools; for the admin-only outbound and identity tools see outbound tools. The full list, and which tools a connection shows, is on the MCP server overview.

Smoke-test a new connection with one cheap call:

ask_knowledge_graph  q="what is this product"  limit=3

The tool shows up in the list even when the connection lacks knowledge:read, so the listing proves nothing. The call itself tells you: if it fails with 403 insufficient_scope, the token does not hold knowledge:read. Reconnect over OAuth and allow "Search what nima knows", or create a key that has knowledge:read.

One failure mode matters more than the rest: a confident "no evidence found" from an agent that only had the repository. If the question is about people, requests or decisions and the agent has not called ask_knowledge_graph or search_signals, it has not looked.

Hand an approved spec to your coding agent

nima can hand a spec to your own coding agent as a brief and record what the agent reports back. Call start_operation with kind implement_spec and target own_harness, then get_operation_brief, then claim_operation_handoff, then report_operation_result.

1. start_operation with kind: "implement_spec", input: {documentId, repositoryId} (repositoryId may be null; pass null to use the spec's own repository, because this is a GitHub repository id, not the id search_code returns) and target: "own_harness". It starts no hosted execution and returns an operation id. The spec must be approved or in progress, otherwise the call fails with 409. If repositoryId is null, nima uses the spec's repository; if the spec has none, the call fails with 400. Repeating the same request for the same spec version returns the same operation; a different request for that version (another member, another target or input) fails with 409.
2. get_operation_brief with that id returns the handoff brief: the spec and what nima knows around it. Run the work in your own environment.
3. claim_operation_handoff marks the handoff as started.
4. report_operation_result records your result as text (1 to 100,000 characters). nima stores it as an external report; it does not attest that tests passed and does not publish code for it.

start_operation, claim_operation_handoff and report_operation_result need the operations:write scope; get_operation_brief needs documents:read. The operations:write scope is not on the consent screen and is not offered in Settings > API keys. Only a workspace owner or admin can create this key, and it acts as the person who created it: in Slack, run /nima mcp-key operations (or say mcp-key operations to @nima) and confirm the card. You receive a 30-day key once. The key carries operations:write, documents:read and knowledge:read. Add it as a second MCP server entry with that bearer token for https://mcp.getnima.io/mcp; start_operation, claim_operation_handoff and report_operation_result appear only on a connection that holds operations:write. get_operation_brief is listed on every connection but only works for the person who started the operation. The agent-operations platform is on; the operation, its states and the hosted-VM alternative are on Agent operations, and the tools on Operation tools.

Reading nima docs from an agent: llms.txt and .md pages

An agent can read these docs as plain text: https://docs.getnima.io/llms.txt lists every page with a one-line description, and adding .md to any page path, without the trailing slash, returns that page as Markdown.

https://docs.getnima.io/llms.txt
https://docs.getnima.io/docs/getting-started/coding-agents.md

Fetch llms.txt first, pick the pages whose descriptions match the task, then fetch those .md URLs. The Markdown version turns the page's callouts, tabs, steps and API parameter tables into plain Markdown and makes every /docs link absolute, so an agent reads only text, lists, tables and code blocks. nima's own Slack assistant searches the same index, so what these pages say is what it tells your team.