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

What it gives your agent

The Polytomic MCP server exposes two tools:

• search - discover Polytomic API paths, methods, parameters, pagination, and auth requirements.
• execute - make Polytomic API requests through the MCP server.

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

Add it to your agent

Most MCP-compatible agents let you register a server with a URL and headers.

1
{
2
  "mcpServers": {
3
    "polytomic-api": {
4
      "url": "https://mcp.polytomic.com/mcp",
5
      "headers": {
6
        "Authorization": "Bearer <api-key>",
7
        "X-Polytomic-Access-Mode": "read-only"
8
      }
9
    }
10
  }
11
}

If your agent supports environment variable interpolation, you can keep the API key out of the config file. The exact syntax depends on the agent, but the setup usually looks like this:

1
{
2
  "mcpServers": {
3
    "polytomic-api": {
4
      "url": "https://mcp.polytomic.com/mcp",
5
      "headers": {
6
        "Authorization": "Bearer ${POLYTOMIC_API_KEY}",
7
        "X-Polytomic-Access-Mode": "${POLYTOMIC_ACCESS_MODE}"
8
      }
9
    }
10
  }
11
}

Recommended local environment variables:

$
export POLYTOMIC_API_KEY="<your-api-key>"
$
export POLYTOMIC_ACCESS_MODE="read-only"

Required configuration

Authorization

Required.

Send your Polytomic API key as a bearer token:

Authorization: Bearer <api-key>

Optional configuration

X-Polytomic-Access-Mode

Optional. Defaults to read-only.

Supported values:

• read-only - safest default for discovery, inspection, and read operations.
• full-access - allows the agent to create, update, and delete resources as well.

Example:

X-Polytomic-Access-Mode: read-only

Only use full-access when you want the agent to be able to create, update, or delete resources on your behalf.

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

Common setups

Read-only user access

1
{
2
  "mcpServers": {
3
    "polytomic-api": {
4
      "url": "https://mcp.polytomic.com/mcp",
5
      "headers": {
6
        "Authorization": "Bearer ${POLYTOMIC_API_KEY}",
7
        "X-Polytomic-Access-Mode": "read-only",
8
        "X-Polytomic-Auth-Mode": "user"
9
      }
10
    }
11
  }
12
}

Full-access user mode

1
{
2
  "mcpServers": {
3
    "polytomic-api": {
4
      "url": "https://mcp.polytomic.com/mcp",
5
      "headers": {
6
        "Authorization": "Bearer ${POLYTOMIC_API_KEY}",
7
        "X-Polytomic-Access-Mode": "full-access",
8
        "X-Polytomic-Auth-Mode": "user"
9
      }
10
    }
11
  }
12
}

Partner mode with default org scope

1
{
2
  "mcpServers": {
3
    "polytomic-api": {
4
      "url": "https://mcp.polytomic.com/mcp",
5
      "headers": {
6
        "Authorization": "Bearer ${POLYTOMIC_API_KEY}",
7
        "X-Polytomic-Access-Mode": "read-only",
8
        "X-Polytomic-Auth-Mode": "partner",
9
        "X-Polytomic-Partner-Org-Id": "${POLYTOMIC_PARTNER_ORG_ID}"
10
      }
11
    }
12
  }
13
}

Environment variables

The hosted MCP server is configured with headers. If your agent supports environment variables, these are the ones most users will want to define locally and reference from their agent config: