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

# Connect AI clients with MCP

> Give Claude and other AI tools live, permission-scoped access to your Hobbes data — no API keys, no code.

## Overview

Hobbes runs a remote [Model Context Protocol](https://modelcontextprotocol.io) server at:

```text theme={null}
https://api.hihobbes.com/mcp
```

Connect an MCP-compatible AI client — Claude, Claude Code, or any tool that supports remote MCP servers — and it can query your sessions, prospects, accounts, transcripts, and funnel metrics, and create Custom Links, using the same data the Hobbes API serves.

Access is authorized with OAuth, not API keys. You sign in with your Hobbes account, choose one organization, and approve a specific set of permissions. The client only ever sees what you approved.

<Note>
  MCP connections are personal. Each teammate connects their own client and approves their own access. To integrate a backend system instead, use an [API key](/guides/authentication).
</Note>

## Connect from Claude

<Steps>
  <Step title="Add the connector">
    In Claude, open **Settings → Connectors → Add custom connector** and enter `https://api.hihobbes.com/mcp`.
  </Step>

  <Step title="Sign in to Hobbes">
    Claude opens the Hobbes sign-in page in your browser. Use your normal Hobbes account.
  </Step>

  <Step title="Approve access">
    Pick the organization this connection may read, review the permissions, and click **Approve**. Members can grant read access; creating Custom Links can only be granted by an organization admin.
  </Step>

  <Step title="Start asking">
    Back in Claude, the Hobbes tools are available immediately. Try: "Which of my demo sessions this week qualified, and why?"
  </Step>
</Steps>

<Note>
  On a Claude Team or Enterprise plan, custom connectors are managed by a workspace admin — ask them to add the connector for your workspace.
</Note>

## Connect from Claude Code

Register the server, then authenticate inside a session:

```bash theme={null}
claude mcp add --transport http hobbes https://api.hihobbes.com/mcp
```

Run `/mcp` in Claude Code, select **hobbes**, and choose **Authenticate**. The same browser sign-in and consent flow applies. Once connected, Claude Code can pull Hobbes data into any task — reports, CRM scripts, prospect research.

## Connect from other clients

Any client that supports remote MCP servers over streamable HTTP with OAuth can connect using the same URL — in Cursor, Windsurf, or VS Code, add it wherever the client configures MCP servers.

For clients that can't connect to remote MCP servers directly — they only launch MCP servers as local processes (stdio), or their remote support lacks OAuth (Codex, at the time of writing) — use the standard [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) bridge. It runs locally as a small proxy and forwards everything to the Hobbes server:

```json theme={null}
{
  "mcpServers": {
    "hobbes": {
      "command": "npx",
      "args": ["mcp-remote", "https://api.hihobbes.com/mcp"]
    }
  }
}
```

The bridge opens the browser sign-in on first use and handles tokens from then on.

<Note>
  Connections made through the bridge appear as **MCP CLI Proxy** on the consent screen and in your connected clients list — that is the bridge's own registered name, not the client behind it.
</Note>

## Permissions and tools

Permissions are chosen on the consent screen and fixed for the life of the connection. The client's tool list shows only the tools its permissions allow.

| Permission           | Tools                                                                                       | What the client can do                                    |
| -------------------- | ------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| `sessions:read`      | `list_sessions`, `get_session`                                                              | Browse demo sessions, outcomes, and qualification results |
| `transcripts:read`   | `get_session_transcript`                                                                    | Read full session transcripts                             |
| `people:read`        | `list_people`, `get_person`                                                                 | Look up prospects and their engagement                    |
| `accounts:read`      | `list_accounts`, `get_account`                                                              | Look up accounts and rollups                              |
| `analytics:read`     | `get_funnel_metrics`                                                                        | Query funnel and conversion metrics                       |
| `custom_links:read`  | `list_custom_links`, `get_custom_link`, `get_custom_link_job`, `list_custom_link_campaigns` | Inspect Custom Links, campaigns, and creation jobs        |
| `custom_links:write` | `create_custom_links`                                                                       | Create personalized Custom Links in batches               |

Every tool is scoped to the organization approved at connection time. The organization is derived from the connection, never accepted from the client.

Some clients add their own approval prompt before running any tool — Claude Code's "Do you want to proceed?" or Claude's tool permission dialog. Those prompts belong to the client, not Hobbes; the permissions you approved at consent apply either way.

<Warning>
  Transcripts contain the verbatim words of everyone in a session. Grant `transcripts:read` deliberately, and see [Transcripts and security](/guides/transcripts-security) before piping transcript text into other systems.
</Warning>

## Creating Custom Links

`custom_links:write` is the one tool that changes data, and it is held to a higher bar:

* Only an **organization admin** can approve it on the consent screen.
* Batches are capped at 200 links per call and run as asynchronous jobs — the client receives a job it can poll with `get_custom_link_job`.
* Requests are idempotent and quota-checked, so a retried or repeated call cannot double-create links. Large batches can take a couple of minutes to be accepted — a client that times out and retries with the same `operation_key` receives the original job instead of duplicates.

If you want a connection that can never write, simply leave the box unchecked at consent — read permissions are independent.

## Manage and revoke connections

Every client you approve appears in **Hobbes → Account Settings → Connected AI clients**, showing its name, organization, permissions, and connection date.

Revoking a connection cuts the client's access on its **next request** — before its token expires. Reconnecting later walks through sign-in and consent again.

<Note>
  Removing a connector inside the AI client does **not** revoke its access — the connection stays valid until you revoke it here. This page is the source of truth for what can reach your data.
</Note>

<Tip>
  Leaving an organization revokes access automatically: tools fail for that org's connections the moment your membership ends, even mid-session.
</Tip>

## Limits and errors

* Requests are rate-limited per connection (HTTP `429` when exceeded); clients back off and retry automatically.
* A `401` means the token expired or the connection was revoked — reconnect from the client.
* A `403` means the connection lacks the permission for that tool, or your organization membership changed.
* A connector that shows **no tools available** after being re-added was likely revoked in between — some clients reuse their stored credentials silently instead of prompting. Refresh the connector's tool list or reconnect to re-authenticate.

## MCP or API key?

|               | MCP connection                                 | API key                                      |
| ------------- | ---------------------------------------------- | -------------------------------------------- |
| Belongs to    | One user, one organization                     | One organization                             |
| Authorization | OAuth sign-in + consent screen                 | Key created in Settings                      |
| Best for      | AI assistants and agent tools used by a person | Backend services, warehouses, scheduled jobs |
| Write access  | Admin-approved at consent                      | `custom_links:write` scope on the key        |

Both surfaces expose the same data with the same organization scoping — pick per use case, or use both.