> ## 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 permission-scoped access to Hobbes data, Playbook updates, and agent publishing.

## 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, such as Claude or Claude Code, and it can
query Hobbes data, create Custom Links, update the Playbook in staging, and
publish an approved agent version. The tools available to the client depend on
the permissions you approve.

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 access, review the permissions,
    and click **Approve**. Only an organization admin can approve Custom Link
    creation, Playbook access, Playbook updates, or agent publishing.
  </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.

If you connected before Playbook and publishing permissions were available,
revoke the old connection and reconnect. Select each new permission you want to
grant. Existing connections never receive new permissions automatically.

| 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 |
| `playbook:read` | `get_playbook`, `list_playbook_suggestions` | Read staging and production Playbooks, versions, links, and ready suggestions |
| `playbook:write` | `preview_playbook_update`, `apply_playbook_update`, `apply_playbook_suggestions` | Preview changes and apply them to staging |
| `agent:publish` | `publish_agent_version`, `get_agent_publish_job` | Publish the exact staged version after confirmation and tests, then check its status |

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>

## Create Custom Links

`custom_links:write` allows a client to create personalized links:

* 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.

## Update the Playbook

Playbook updates follow a preview-first process:

1. The client reads the current staging and production Playbooks with
   `get_playbook`.
2. `preview_playbook_update` validates the proposed changes and returns a
   before-and-after summary without changing staging.
3. After you review the summary, `apply_playbook_update` applies that exact
   preview to staging. Previews expire after 24 hours, and a change to staging
   invalidates an older preview.
4. Open the staging link returned by Hobbes and test the updated agent.

The client can also list ready Hobbes suggestions. Applying a suggestion uses
the exact stored change. Use the preview flow when you want to edit the wording
first.

<Note>
  Legacy Playbooks can be read through MCP, but they cannot be updated until they
  are migrated in Hobbes.
</Note>

## Publish an agent version

Publishing requires the separate `agent:publish` permission. Hobbes always:

* asks for confirmation in the AI client before creating the publish job;
* publishes the exact current staging version, not an inferred or older version;
* runs the existing conversation tests before changing production; and
* returns a job that the client checks until it succeeds or fails.

Grant `agent:publish` only when the connection should be able to change the
production agent. Playbook updates can remain limited to staging by granting
`playbook:write` without `agent:publish`.

If you want a connection that cannot change data, leave all write and publishing
permissions unselected.

## 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 permissions at consent | Optional `custom_links:write`, `playbook:write`, and `agent:publish` scopes |

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


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