Nomic MCP server

The Nomic MCP server lets AI clients such as Cursor, Claude Code, and GitHub Copilot in VS Code work with your Nomic instance. From your editor or terminal you can:

• Find files and projects, and run Nomic agents and workflows on them.
• Wait for a run to finish, then read its answer and artifacts, or export a table to CSV or Excel.
• If you are an organization admin, review spend, audit logs, users, and API keys.

The server uses the Model Context Protocol, so any client that supports remote MCP servers with custom headers can connect. It uses the same API keys, scopes, and permissions as the Nomic HTTP API, and is available on Business and Enterprise organization instances.

Before you begin​

You need:

1. Your server URL. It is your Nomic address followed by /mcp, for example https://acme.drive.nomic.ai/mcp. The Developer → MCP page on your instance shows it, along with ready-to-copy configuration for Cursor, Claude Code, and VS Code.
2. An API key. Open Developer → API Keys, select Create Key, give it a name such as "Cursor on my laptop", and keep the developer scope selected. Admins can add admin scopes as well; see Choose scopes. Copy the key when it appears. Nomic shows it only once.

The key acts as you. Every tool call runs with your project and file access, appears in the audit log under your name, and counts toward your spend.

Connection details​

HTTP Basic authentication also works, with the API key as the username and an empty password.

Set up your client​

The examples read the key from an environment variable named NOMIC_API_KEY, so it never lands in a file you might commit. Set it in your shell profile (~/.zshrc, ~/.bashrc, or your Windows environment variables), then restart the client so it picks the variable up:

export NOMIC_API_KEY="npk_..."

In each example, replace <your-domain> with your Nomic domain.

claude mcp add --transport http --scope user nomic \
  https://<your-domain>.nomic.ai/mcp \
  --header "Authorization: Bearer $NOMIC_API_KEY"

{
  "mcpServers": {
    "nomic": {
      "type": "http",
      "url": "https://<your-domain>.nomic.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${NOMIC_API_KEY}"
      }
    }
  }
}

[mcp_servers.nomic]
url = "https://<your-domain>.nomic.ai/mcp"
bearer_token_env_var = "NOMIC_API_KEY"

{
  "mcpServers": {
    "nomic": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://<your-domain>.nomic.ai/mcp",
        "--header",
        "Authorization:${NOMIC_AUTH_HEADER}"
      ],
      "env": {
        "NOMIC_AUTH_HEADER": "Bearer npk_..."
      }
    }
  }
}

Check the connection​

Ask your client:

Call the Nomic get_current_api_key tool and tell me who I'm signed in as and which tools I can use.

The answer names the key's owner, its scopes, and the tools it can call. If a tool you expect is missing, the key does not have the scope for it. See Troubleshooting.

Examples​

You don't need to name tools. Describe the task and the client picks the tools. Every example on this page works with a key that has the developer scope.

Run an agent on project files​

The client finds the project and file, then calls run_agent, which starts a Nomic agent and waits for it to finish. The agent does the work inside Nomic with your project's drawings and specs, then the client reads the result.

Each agent run is a normal Nomic session. Open it at https://<your-domain>.nomic.ai/assistant/<agentId> to see what the agent read and check each citation. The run above looks like this in Nomic:

Continue a run​

Ask a follow-up and the client calls followup_and_wait with the same agent, so the agent keeps its earlier context:

Ask the Nomic agent from the submittal review to draft reviewer comments for each deviation.

More prompts to try​

• "List my Nomic workflows and run the RFI response workflow on RFI-042.pdf in the Harbor Point project."
• "Create a Nomic project called Riverside Clinic, project number 24-118, and add Dana and Sam as members."
• "Show me my Nomic agents that failed this week and what went wrong."
• "How much did my last Nomic agent run cost?"

For admin examples, such as reviewing spend or disabling a user, see MCP for IT and admins.

Prompts​

The server also publishes prompts, ready-made instructions that walk the client through a task. Clients usually list them as slash commands. In Claude Code, for example, type /mcp__nomic__orchestrate-agent. A prompt appears only when your key can call every tool it uses. See Prompts for the full list.

Approvals and safety​

Nomic marks each tool as read-only, write, or destructive, and most clients ask before running a tool that makes changes. Keep those approvals on. Approve writes such as run_agent or create_project knowingly, and read destructive calls such as delete_agent or disable_user carefully before you allow them.

Documents and agent answers returned to your client can contain text that reads like instructions. Check what a tool call will do before you approve it, especially when other MCP servers are connected in the same session.

Create one key per client or automation. You can then revoke a single laptop without breaking the others.

Troubleshooting​

401 Unauthorized when connecting​

The key is missing, mistyped, revoked, or expired. Check that the header reads exactly Authorization: Bearer npk_.... If the configuration reads the key from an environment variable, check that the client was started from an environment where it is set.

403 Forbidden when connecting​

The key is valid, but its owner's account is disabled. Ask an admin.

The client opens a browser sign-in or reports an OAuth error​

The client did not send the header, so it fell back to OAuth, which Nomic does not support. Compare your configuration with the examples, or use mcp-remote as described under Other clients.

A tool is missing​

Tools appear only when the key's scopes allow them. Admin tools also require the key's owner to be an organization admin. Call get_current_api_key to see what the key can do. After changing scopes or keys, reconnect the server so the client reloads the tool list.

run_agent returned timedOut: true​

A single call waits up to 14 minutes. The agent keeps running. Ask the client to call wait_for_agent with the returned agentId. Do not start the agent again.

A call failed with rate_limited​

Wait for the number of seconds in retryAfterSec, then retry. Starting agents, follow-ups, uploads, parse jobs, and artifact exports share a budget of 30 per minute. See Rate limits.

A call failed with payment_required​

You or your organization reached a spend limit. Ask an admin.

An upload is rejected as too large​

upload_file sends the file inline and accepts files up to 15 MB. Upload larger files in the Nomic app, or with POST /api/v0/files/upload.

Long calls drop behind a corporate proxy​

Tool calls that wait on an agent stream their response for up to 15 minutes. Your network must allow long-lived HTTPS responses from your Nomic domain.

Related​

• MCP tools: every tool, prompt, and resource, with scopes.
• MCP for IT and admins: roll-out, access control, auditing, and revoking access.
• Agent API: the HTTP API behind the agent tools.