> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://apidocs.polytomic.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://apidocs.polytomic.com/_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:

```text
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:

```text
Authorization: Bearer ${POLYTOMIC_API_KEY}
```

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

```text
POLYTOMIC_API_KEY
```

The environment variable value must 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:

| Field                 | Value                           |
| --------------------- | ------------------------------- |
| Name                  | `Polytomic`                     |
| Remote MCP server URL | `https://mcp.polytomic.com/mcp` |

6. Select **Add** and complete the Polytomic OAuth flow.

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

## Configure ChatGPT

ChatGPT supports OAuth for remote MCP connectors when Developer Mode is enabled.

1. Go to [chatgpt.com](https://chatgpt.com/).
2. Select your name in the bottom left.
3. Open **Settings**.
4. Open **Apps**.
5. In **Advanced Settings**, turn on **Developer Mode**.
6. Create an app and name it `Polytomic`.
7. For **Connection**, select **Server URL**.
8. Enter the MCP server URL:

| Field          | Value                           |
| -------------- | ------------------------------- |
| Server URL     | `https://mcp.polytomic.com/mcp` |
| Authentication | `OAuth`                         |

9. Select **I understand and want to continue**.
10. Select **Create**.
11. Complete the Polytomic sign-in and authorization flow.

After authorization, you can use Polytomic in both the web and desktop versions of ChatGPT.

## Configure Codex Desktop

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

| Field                | Value                           |
| -------------------- | ------------------------------- |
| Name                 | `polytomic-api`                 |
| URL                  | `https://mcp.polytomic.com/mcp` |
| Bearer token env var | `POLYTOMIC_API_KEY`             |

Define the environment variable before launching Codex Desktop:

```bash
export POLYTOMIC_API_KEY="<your-api-key>"
```

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

```bash
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:

```bash
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

```bash
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.

```bash
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:

```text
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:

```text
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:

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

## Verify your MCP connection

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

```text
Use the Polytomic MCP to determine my identity
```

The response will be something like this:

```text
You're Joe, an admin at the "Acme Inc." organization.

Email: joe@acme.com
Role: admin
```