> ## 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 or a second credentials system.

Create an API key in **Settings → API / MCP**, then connect ChatGPT or Claude with that same key. The Settings page also shows the server URL for your Octanist host.

## Server URL

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

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

## Authentication

Use an API key from the table on **Settings → API / MCP**. The same key authenticates REST. There is no separate MCP key and no OAuth.

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`, or the URL copied from Settings → API / MCP.
4. Choose **Token** (or API key) authentication. Paste an API key from Settings → API / MCP. Prefer sending it as `Authorization: Bearer YOUR_API_KEY`. If the form has a header field instead, use `X-API-KEY` with the raw key.
5. Create the connector. 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**. Octanist does not use OAuth.
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).