Troubleshooting

If a client can't reach Primitive MCP, start here. If none of these apply, contact hello@primitive.tech with the client name, version, and the error message.

"Token expired" or 401 after working previously

Most supported clients refresh OAuth tokens automatically. If yours doesn't:

1. Remove the Primitive MCP server from your client.
2. Re-add it from the matching section under Setup.
3. Complete the OAuth flow again.

If you recently revoked the client from Connected applications, this is expected — reconnect to restore access.

"Insufficient scope"

The tool you called requires a scope your client wasn't granted. Primitive MCP uses two scopes:

• mcp:read — read-only.
• mcp:write — state-changing.

If your client only requested mcp:read and you want it to also call write tools, you'll need to disconnect and reconnect — the consent screen will show the broader scope list. Re-approve only if you actually want that level of access. You can confirm the currently-granted scopes by visiting Connected applications before reconnecting.

"Unsupported client" or registration denied

Primitive MCP only accepts connections from reviewed clients (see Supported clients). If your client gets denied during dynamic registration:

• Confirm the client is on the allowlist.
• If it isn't, email hello@primitive.tech with the client name and version to request review.
• In the meantime, use one of the supported clients for the same task.

"Wrong audience" or token rejected

A bearer token issued for a different resource won't work against Primitive MCP. Confirm your client is pointed at the right URL:

curl -sf https://mcp.primitive.tech/.well-known/oauth-protected-resource | jq

The resource field should match the URL you entered in your client. If it doesn't, fix the URL in your client config and re-register the server. (Requires jq; install via brew install jq or apt install jq, or drop the pipe and read raw JSON.)

Reset local auth state

The mcp-remote shim (used by Gemini CLI and some community clients) caches OAuth tokens per host in ~/.mcp-auth/. If a client that uses it is stuck in a bad state, target only the Primitive cache directory so other servers' tokens aren't affected:

rm -rf ~/.mcp-auth/mcp.primitive.tech

Then restart the client and reconnect. This is safe — it only forces you through the OAuth flow again.

Other clients cache tokens in their own locations:

• Claude Code — managed by the claude CLI. Remove the server (claude mcp remove primitive), then re-add it following the Claude Code setup.
• Codex CLI / IDE — remove the [mcp_servers.primitive] block from ~/.codex/config.toml, restart Codex, then add it back from the Codex setup. Codex picks up the change on next start.
• VS Code / Cursor — re-run the editor's "Add MCP Server" flow; tokens live in the editor's secret storage.

If you can't tell where your client stores its tokens, the safest reset is to revoke the client from Connected applications and reconnect.

Plan-tier gotchas

A few clients require specific plans for custom MCP connectors:

• Claude.ai (web) — connectors require Pro, Team, or Enterprise.
• Claude Desktop — custom connectors require Pro, Max, Team, or Enterprise.
• ChatGPT — custom connectors require Pro or Plus, and you must enable Developer Mode under Settings → Connectors → Advanced settings.

Anthropic and OpenAI change connector eligibility periodically — verify the current rules on the vendor's pricing page if your account doesn't show the option.

If you don't see the "Add custom connector" option, your plan is the most likely cause.

Connection works, but tools don't appear

After connecting, ask the agent to list available tools. If none show up:

• Confirm the OAuth flow actually completed (the consent screen redirected back to your client without an error page).
• Check that the connection is live: run whoami and confirm it returns your username and email.
• Restart the client. Some MCP clients only discover tools at startup.

Where to file issues

For bugs in Primitive MCP itself, email hello@primitive.tech with:

• Client name and version.
• The full error message (and request id from the response headers if you have it).
• What you were trying to do.

For client-side bugs (the consent screen never opened, the CLI crashes), file those with the client's vendor first — they usually have a --debug or verbose mode that captures the failing request.