MCP server

Polytomic provides a hosted MCP server for LLM agents and other MCP-compatible tools that need to explore and use the Polytomic API.

Use this when you want an agent to discover the right Polytomic endpoints and make API calls without hard-coding paths by hand.

MCP server URL

Use the production endpoint:

https://mcp.polytomic.com/mcp

The hosted server uses Streamable HTTP.

Authentication options

The hosted MCP server supports two authentication methods:

• OAuth - sign in to Polytomic from the MCP client. Use this for clients that support remote MCP OAuth. Claude Desktop supports OAuth only.
• API key bearer token - send a Polytomic API key as an authorization bearer token. Use this for clients that support headers or a bearer-token environment variable.

OAuth sessions run as user-mode sessions for the organization selected during the OAuth flow. Partner mode requires API key bearer authentication with headers.

For API key authentication, set this header:

Authorization: Bearer ${POLYTOMIC_API_KEY}

If your client has a dedicated Bearer token env var field, enter only the variable name:

POLYTOMIC_API_KEY

The environment variable value should be the raw API key, not the Bearer prefix.

What it gives your agent

The Polytomic MCP server exposes these core tools:

• search - discover Polytomic API paths, methods, parameters, pagination, and auth requirements.
• execute - make Polytomic API requests through the MCP server.
• submit_mcp_feedback - send structured feedback about MCP friction or missing capabilities.

For most agent workflows, the agent should use search first and execute second.

Configure Claude Desktop

Claude Desktop supports OAuth for remote MCP connectors.

1. Open Claude Desktop.
2. In the left pane, open Customize.
3. Open Connectors.
4. Select Add Custom Connector.
5. Enter:

6. Select Add and complete the Polytomic OAuth flow.

Do not add an API key header for Claude Desktop. It uses OAuth for this connector and does not expose optional Polytomic headers in this setup.

Configure Codex Desktop

1. Open Codex Desktop.
2. Open Settings.
3. Open MCP Servers.
4. Select Add server.
5. Select Streamable HTTP.
6. Enter:

Define the environment variable before launching Codex Desktop:

$
export POLYTOMIC_API_KEY="<your-api-key>"

On macOS, you can also set it for GUI apps with launchctl and then restart Codex Desktop:

$
launchctl setenv POLYTOMIC_API_KEY "<your-api-key>"

You can also set the token directly in Headers with key Authorization and value Bearer <your-api-key>. The bearer token environment variable is preferred because it keeps the API key out of the UI and config file.

For optional Polytomic headers, use the Headers section. For example, set X-Polytomic-Access-Mode to read-only for discovery and read-only workflows.

Configure Claude Code CLI

OAuth

Add the remote MCP server:

$
claude mcp add --transport http --scope user polytomic-api https://mcp.polytomic.com/mcp

Start Claude Code and complete the OAuth prompt when the server connects. You can use /mcp inside Claude Code to check the server status.

API key bearer token

$
export POLYTOMIC_API_KEY="<your-api-key>"
$
$
claude mcp add --transport http --scope user polytomic-api \
>
  https://mcp.polytomic.com/mcp \
>
  --header "Authorization: Bearer ${POLYTOMIC_API_KEY}" \
>
  --header "X-Polytomic-Access-Mode: read-only"

This command stores the expanded authorization header in your Claude Code MCP configuration. Use OAuth if you do not want an API key stored in the Claude Code config.

Configure Codex CLI

Codex uses API key bearer authentication for this server.

$
export POLYTOMIC_API_KEY="<your-api-key>"
$
$
codex mcp add polytomic-api \
>
  --url https://mcp.polytomic.com/mcp \
>
  --bearer-token-env-var POLYTOMIC_API_KEY

Codex stores the environment variable name and reads the API key from your environment at runtime.

Optional headers

X-Polytomic-Access-Mode

Optional. Set this to read-only to apply read-only mode for discovery, inspection, and read operations.

Example:

X-Polytomic-Access-Mode: read-only

X-Polytomic-Auth-Mode

Optional. Defaults to user.

Supported values:

• user - use this with a user API key generated from the user settings page.
• partner - use this with a partner API key from a partner account.

Example:

X-Polytomic-Auth-Mode: partner

When you use partner, the agent can act across Polytomic organizations available to that partner account.

X-Polytomic-Partner-Org-Id

Optional.

Use this when you are using partner mode and want to provide a default organization scope. Typically, this will be your partner organization ID.

Example:

X-Polytomic-Partner-Org-Id: 00000000-0000-4000-8000-000000000000

Verifying your MCP connection

Execute this prompt to verify that your Polytomic MCP is operational:

Use the Polytomic MCP to determine my identity

The response will be something like this:

You're Joe, an admin at the "Acme Inc." organization.
Email: joe@acme.com
Role: admin