> ## Documentation Index
> Fetch the complete documentation index at: https://octanist.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP

> Connect ChatGPT and Claude to the Octanist public API

The Octanist MCP server exposes the existing public API over [Model Context Protocol](https://modelcontextprotocol.io/). It does not add REST paths.

ChatGPT custom connectors sign in with OAuth. Claude, Cursor, and other header-based clients use an API key from **Settings → API / MCP**. That page also shows the copyable server URL.

## Server URL

```
https://octanist.com/api/mcp
```

The transport is streamable HTTP. Use that URL as written. Do not put credentials in the URL or query string.

## Authentication

The same MCP URL accepts two auth methods.

### OAuth (ChatGPT)

ChatGPT custom connectors use OAuth. Sign in to Octanist, pick an organization, and click **Allow access**. Do not paste an API key in ChatGPT.

New accounts can sign up and verify email during that flow, then finish consent.

Reconnecting ChatGPT and picking another organization mints new tokens for that org. Existing tokens stay on the first org.

### API key (Claude, Cursor, REST)

Claude remote connectors, Cursor, and REST use an API key from the table on **Settings → API / MCP**. The same key authenticates REST.

Send the key on every MCP request as either:

* `X-API-KEY: YOUR_API_KEY` (same header as REST)
* `Authorization: Bearer YOUR_API_KEY`

<Warning>
  Keep your API key out of client-side code and public repositories. Do not
  commit MCP config that contains the key.
</Warning>

## Connect ChatGPT

Paid ChatGPT only (Plus, Pro, Business, Enterprise, or Edu). Free ChatGPT cannot add this connector.

OpenAI's account-specific UI is in [Developer mode and full MCP connectors](https://help.openai.com/en/articles/12584461-developer-mode-and-full-mcp-connectors-in-chatgpt).

1. Enable **Developer mode**. Look under Settings → Apps → Advanced settings, or Settings → Security and login, depending on the account.
2. Go to Settings → Connectors (some accounts still say Plugins) and choose **Create**.
3. Name it `Octanist`. Set the MCP server URL to `https://octanist.com/api/mcp`. Prefer the URL copied from Settings → API / MCP.
4. Choose **OAuth**. Do not paste an API key.
5. ChatGPT opens Octanist. Sign in (or sign up and verify email), pick an organization, and click **Allow access**.
6. In a new chat, open **+**, enable Octanist, and ask something only Octanist can answer, such as listing recent leads.

## Connect Claude

Works as a remote custom connector on [claude.ai](https://claude.ai), Claude Desktop, Cowork, and mobile. Anthropic's cloud calls the public HTTPS URL. Official steps are in [Get started with custom connectors](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp) and [Remote MCP](https://claude.com/docs/connectors/custom/remote-mcp).

### Pro, Max, and Free

1. Go to Customize → Connectors → **Add custom connector**.
2. Name it `Octanist`. Set the URL to `https://octanist.com/api/mcp`, or the URL copied from Settings → API / MCP.
3. Set authentication to **None**.
4. Under **Request headers**, add one of:

   * `x-api-key` = your API key
   * `authorization` = `Bearer YOUR_API_KEY` (include the word `Bearer`)

   Claude sends the header value as typed. If you choose `authorization`, type `Bearer ` then the key, including the space.
5. Add the connector. In a chat, open **+** → Connectors and enable Octanist.

### Team and Enterprise

An Owner must add the connector first under Organization settings → Connectors. Members then go to Customize → Connectors and click **Connect**.

If your Claude account has no Request headers field, add the server in Claude Code:

```bash theme={null}
claude mcp add --transport http octanist https://octanist.com/api/mcp \
  --header "X-API-KEY: YOUR_API_KEY"
```

## Other clients

Most MCP clients that support streamable HTTP and request headers can use the same URL and API key.

<AccordionGroup>
  <Accordion title="Cursor">
    Add this to `.cursor/mcp.json` or Cursor Settings → MCP. Replace `YOUR_API_KEY` with a key from Settings → API / MCP.

    ```json theme={null}
    {
      "mcpServers": {
        "octanist": {
          "url": "https://octanist.com/api/mcp",
          "headers": {
            "X-API-KEY": "YOUR_API_KEY"
          }
        }
      }
    }
    ```
  </Accordion>
</AccordionGroup>

## Tools

Each tool maps 1:1 onto an existing public REST operation. Arguments follow the same query parameters or JSON body as that endpoint. Request and response details live on the REST pages below.

| Tool | REST | Docs |
| - | - | - |
| `check_api` | `GET /api/check` | [Check API Key](/docs/api-reference/endpoint/check) |
| `list_leads` | `GET /api/leads` | [Get Leads](/docs/api-reference/endpoint/get-leads) |
| `get_lead` | `GET /api/leads/{id}` | [Get Lead by ID](/docs/api-reference/endpoint/get-lead) |
| `create_lead` | `POST /api/leads` | [Create Lead](/docs/api-reference/endpoint/create-lead) |
| `update_lead` | `PATCH /api/leads` | [Update Lead](/docs/api-reference/endpoint/update-lead) |
| `get_stats` | `POST /api/stats` | [Get Stats](/docs/api-reference/endpoint/stats) |
| `get_ad_spend` | `POST /api/ad-spend` | [Get Ad Spend](/docs/api-reference/endpoint/ad-spend) |

`GET /api/check` and `POST /api/check` run the same handler. The MCP tool uses GET. Stats and ad spend stay POST, matching the REST API.

`list_leads` and `get_lead` return the converting pixel `session` plus scoped journey `sessions`. Flattened click IDs, UTMs, consent, website, and path stay on the lead. See [Full Lead Object](/docs/api-reference/endpoint/get-leads#full-lead-object).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.