Logo
  • Documentation
  • GPU RMA Diagnostic Toolkit — User Guide
MCP Server
  • Primitive MCP
  • Available MCP tools
  • Managing connected applications
  • Security best practices
  • Troubleshooting

Primitive MCP

Primitive's hosted MCP server at mcp.primitive.tech — connect Claude, ChatGPT, Codex, Cursor, Copilot, and Gemini over OAuth.

Primitive MCP is Primitive's official Model Context Protocol server. It's a remote MCP server with OAuth that lets AI clients securely access your Primitive resources — hardware, jobs, projects, files, and billing — at:

https://mcp.primitive.tech/mcp

The server is hosted by Primitive. There is nothing to install or self-host.

Supported clients

Primitive MCP only accepts connections from AI clients on the approved list below. Primitive does not audit third-party client source code — review each vendor's own security documentation before connecting any client with mcp:write.

  • Anthropic — Claude Code, Claude Desktop, Claude.ai
  • OpenAI — ChatGPT, Codex (CLI and IDE)
  • GitHub — VS Code with Copilot, Copilot CLI, Copilot coding agent
  • Google — Gemini CLI
  • Other — Cursor
  • Developer — mcp-inspector (Primitive contributors)

Enforcement status: Allowlist enforcement on dynamic client registration is tracked separately and is not yet active in the deployed backend. Until enforcement ships, the policy here describes intended behavior; any public client with a loopback redirect URI can currently register. Do not rely on the allowlist as a security boundary until enforcement is deployed.

If you need a client not listed above (Windsurf, Zed, JetBrains, Amazon Q, Warp, Continue, Cline, goose, Replit, LibreChat, Mistral Le Chat, Microsoft Copilot Studio, or anything else from the official MCP clients index), email hello@primitive.tech with the client name and version.

If Anthropic, OpenAI, GitHub, or another vendor publishes a security advisory for a specific client version, follow their guidance. Primitive does not maintain per-version trust lists — treat client updates like any dependency update and apply security patches promptly.

Read versus write

Most tools on Primitive MCP require one of two scopes:

  • mcp:read — list and inspect organizations, projects, hardware, jobs, files, and billing data. Safe to grant broadly for general-purpose agents. Org admins should note that billing and invoice tools live under mcp:read and return sensitive financial data — see Available MCP tools — Billing before granting mcp:read to cloud-hosted or web-browsing agents.
  • mcp:write — modify resources: rename hardware, update jobs, cancel job runs, change member roles, revoke invitations, delete files.

A small set of utility tools (health, whoami) are unscoped — they don't require either mcp:read or mcp:write. Everything else is gated by exactly one scope.

Grant mcp:read freely. Require human confirmation before any mcp:write action. See Security best practices for the full guidance.

First connect

Every setup flow ends with an OAuth consent screen hosted at mcp.primitive.tech:

  • Verify the URL bar shows mcp.primitive.tech. Any other domain means you may be on a phishing page — close the tab.
  • Sign in with your Primitive account.
  • Review the client name the request is coming from (e.g., Claude Code, Cursor, ChatGPT) — if it isn't the client you're configuring, cancel.
  • Review the scopes the client is asking for (mcp:read, mcp:write, or both).
  • Approve to issue the OAuth token, or decline to keep the client disconnected.

The token is bound to your user and the specific client. You can revoke it at any time from Managing connected applications.

Setup

Snippets below use https://mcp.primitive.tech/mcp as the server URL. On first tool call, every client opens the First connect consent screen in your browser.

Claude Code

Claude Code is Anthropic's official coding CLI.

claude mcp add --transport http primitive https://mcp.primitive.tech/mcp

Then in a session, type /mcp to see the server. If your Claude Code version doesn't accept --transport http, run claude mcp add --help for the current flag form.

Claude Desktop

Custom connectors require Pro, Max, Team, or Enterprise on Claude Desktop (verify against Anthropic's current pricing).

  1. Open Claude Desktop → Settings → Connectors → Add custom connector.
  2. Set Name to Primitive and URL to https://mcp.primitive.tech/mcp. Save.

Claude.ai

Connectors require Pro, Team, or Enterprise on Claude.ai (verify against Anthropic's current pricing).

  1. Sign in to claude.ai → Settings → Connectors → Add custom connector.
  2. Set Name to Primitive and URL to https://mcp.primitive.tech/mcp. Save.

ChatGPT

Custom connectors require Pro or Plus on ChatGPT with Developer Mode enabled (verify against OpenAI's current pricing).

  1. Sign in to chat.openai.com → Settings → Connectors → Advanced settings → toggle Developer Mode on.
  2. From Connectors, click Create:
    • Name: Primitive
    • URL: https://mcp.primitive.tech/mcp
    • Authentication: OAuth
  3. Save.

OpenAI changes this UI frequently. If you don't see Connectors, check OpenAI's help center for the current location of Developer Mode on your account tier.

Codex

OpenAI's Codex ships as both a CLI and an IDE extension. Both read ~/.codex/config.toml:

[mcp_servers.primitive]
url = "https://mcp.primitive.tech/mcp"

Then start Codex:

codex

Codex's MCP support is evolving. CLI subcommand names and config keys have changed in past releases — if the snippet doesn't work as written, check the current Codex docs.

Cursor

Requires Cursor 0.46 or later. (Earlier versions may need "type": "http" inside the server block.)

Open .cursor/mcp.json in your project root (or ~/.cursor/mcp.json to make it global):

{
  "mcpServers": {
    "primitive": {
      "url": "https://mcp.primitive.tech/mcp"
    }
  }
}

Reload Cursor (Cmd/Ctrl+Shift+P → Developer: Reload Window).

VS Code with GitHub Copilot

  1. Open the Command Palette (Cmd/Ctrl+Shift+P).
  2. Run MCP: Add Server → choose HTTP.
  3. Set URL to https://mcp.primitive.tech/mcp and Name to Primitive. Save.
  4. Run MCP: List Servers → select Primitive → Start Server → complete the URL-handler OAuth.

To call Primitive tools, switch Copilot Chat to Agent mode (the mode selector in the chat input) and ask in natural language — for example, List my Primitive projects. MCP servers in Copilot are not addressed with @mentions.

GitHub Copilot CLI

The GitHub Copilot CLI is on GitHub's MCP roadmap, but the subcommand surface for adding MCP servers has not stabilized. Run gh copilot --help for the current subcommand name and pass:

https://mcp.primitive.tech/mcp

See GitHub's official MCP docs for the canonical configuration steps.

GitHub Copilot coding agent

This is the highest-blast-radius MCP configuration in Primitive. An org-level setting applies to every Copilot coding agent run for every developer in the organization. Double-check the URL before saving.

The Copilot coding agent runs in GitHub's cloud, so configuration happens on the GitHub side — there is no local config to edit. Requires repository or organization admin rights.

  1. In GitHub, open your repository (or organization) Settings → Copilot → MCP servers.
  2. Click Add server and fill in:
    • Name: Primitive
    • URL: https://mcp.primitive.tech/mcp
    • Authentication: OAuth
  3. Save.

Because the cloud agent can't open a browser, an authorized user has to pre-authorize the connection manually: open the URL GitHub provides in the agent's settings UI (or its first run log), sign in to Primitive, and approve. The OAuth token is bound to the Primitive account of the user who completes the consent screen — for org-level configs, use a shared service or bot account so individual team-member changes don't break the integration. Until pre-authorization is complete, the first tool call from the agent fails with 401 Unauthenticated.

Gemini CLI

Gemini CLI connects via the mcp-remote shim. Open ~/.gemini/settings.json (create if missing):

{
  "mcpServers": {
    "primitive": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.primitive.tech/mcp"]
    }
  }
}

When Gemini CLI ships native HTTP transport, this snippet will be updated.

mcp-inspector

For Primitive contributors only. End users should pick a supported client instead.

Requires the allowlist deployment. The mcp-inspector pre-registration ships with Primitive's MCP OAuth allowlist deployment. Until that's live in the environment you're targeting, this flow fails with a client-rejection error.

mcp-inspector is the official MCP debugger. Primitive maintains a known client_id value of mcp-inspector for use against per-developer cloudflared tunnels.

npx @modelcontextprotocol/inspector

In the Inspector UI:

  • Transport: HTTP
  • URL: https://mcp.<username>.primitive.tech/mcp
  • Client ID: mcp-inspector (case-sensitive)
  • If Inspector defaults to http://localhost/... for its redirect target, change it to http://127.0.0.1/... — the pre-registered redirect URIs are 127.0.0.1-only.

See development/ in the monorepo for cloudflared tunnel setup.

Headless and remote agents

Every client above signs in through a browser on the machine it runs on. An agent that cannot open one — on a remote machine, over SSH, in a container, or one you drive from your phone — sends an MCP token instead.

  1. In the Primitive web app, open Account settings → Tokens and go to MCP Tokens. This works from any device, a phone too.

  2. Name the token, choose the organizations and the permissions it can use, and choose an expiry. An MCP token lasts at most one year.

  3. Copy the token. It is shown once.

  4. On the agent's machine, put it in an environment variable:

    export PRIMITIVE_MCP_TOKEN="<the token>"
  5. Add the server with the line for your client. Each form reads the variable, so the token stays out of the client's config file.

Claude Code — the single quotes keep the shell from putting the token itself into the config:

claude mcp add-json --scope user primitive '{"type":"http","url":"https://mcp.primitive.tech/mcp","headers":{"Authorization":"Bearer ${PRIMITIVE_MCP_TOKEN}"}}'

With the header set, Claude Code does not start a browser sign-in. A token that the server refuses shows as a failed connection.

If you added primitive with the browser setup above, remove that entry first. The browser setup adds a local entry, and a local entry wins over a user entry. Run this in the project directory where you added it:

claude mcp remove primitive

Codex:

codex mcp add primitive --url https://mcp.primitive.tech/mcp --bearer-token-env-var PRIMITIVE_MCP_TOKEN

Cursor — in ~/.cursor/mcp.json:

{
  "mcpServers": {
    "primitive": {
      "url": "https://mcp.primitive.tech/mcp",
      "headers": {
        "Authorization": "Bearer ${env:PRIMITIVE_MCP_TOKEN}"
      }
    }
  }
}

A project .cursor/mcp.json wins over ~/.cursor/mcp.json. If a project file also has primitive, remove that entry first.

An MCP token works only on the MCP server, not on the Primitive API. It gets mcp:write only when its permissions include a change permission; a read-only token can call only mcp:read tools. Delete a token under MCP Tokens to stop it at once.

Next steps

  • Available MCP tools — every tool, split by mcp:read / mcp:write.
  • Security best practices — required reading before granting mcp:write.
  • Managing connected applications — view and revoke OAuth grants.
  • Troubleshooting — token / scope / wrong-audience issues.

On This Page

Supported clientsRead versus writeFirst connectSetupClaude CodeClaude DesktopClaude.aiChatGPTCodexCursorVS Code with GitHub CopilotGitHub Copilot CLIGitHub Copilot coding agentGemini CLImcp-inspectorHeadless and remote agentsNext steps
Logo

© 2026 Primitive Instruments Corporation.
All rights reserved.

DocsBrandContactCareersPrivacy PolicyTerms of Service
Logo