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

# Connect an MCP host

> Add the Parable MCP server to Claude Code, Claude, Cursor, or VS Code, with OAuth sign-in or an MCP token.

The Parable MCP server lets an AI assistant, which MCP calls a **host**, read
one Workspace. The host can query Provider data with SQL, read published
Plots, check Provider connections and Taps, and read the Workspace's Powers.
Every call acts as one person, with that person's roles, and only reads.
[Tools, prompts, and limits](/mcp/tools.md) lists what the server offers.

The server address for a Workspace is:

```text theme={null}
https://mcp.parable.work/mcp/workspaces/<workspace-slug>
```

The slug is the first part of your Workspace's address: `acme-corp` in
`acme-corp.parable.work`. The path names the Workspace. Do not send an
`X-Tenant` header.

## Choose how the host signs in

| Way | Use it for | What the host holds |
| - | - | - |
| [Sign in with OAuth](#sign-in-with-oauth) | A host that supports MCP sign-in, such as Claude Code. Nobody copies a token. | A grant for one Workspace that only reads. The host refreshes it. |
| [Use an MCP token](#use-an-mcp-token) | A host that cannot sign in, or a script that runs without a browser. | A personal access token for MCP, which you create in the app. |

Both ways read with the roles of the person who signed in or created the
token. Neither way reaches a different Workspace.

## Allow external agents

Do this step first, for either way. It is off in every Workspace until a
person turns it on.

1. In the Workspace app, open **Protection → Access Tokens**.
2. Turn on **Allow external agents**.

This setting needs a role that manages sign-in for the Workspace
(`tenant.auth.manage`). While it is off:

* Every MCP token and every sign-in from a host is refused with `403`
  (code `WA-PAT-006`).
* Nobody can create an MCP token.
* The sign-in page does not offer the Workspace.

Turning the setting off revokes nothing. When it is on again, MCP tokens
work again, and a person who signed in from a host may need to sign in
again.

> [!NOTE]
>
> A host sends what it reads to its own model provider. Your Workspace's AI
> processor settings do not cover that provider.

## Sign in with OAuth

**1. Add the server without a token**

Follow the tab for your host.

**Claude Code**

```bash theme={null}
claude mcp add --transport http parable \
  https://mcp.parable.work/mcp/workspaces/acme-corp
```

In Claude Code, run `/mcp`. Choose `parable`, then **Authenticate**.

**Claude**

Add the server as a custom connector in Claude on the web or in
Claude Desktop.

1. Open **Customize > Connectors**.
2. Select **Add custom connector**.
3. Type a name, such as `Parable`, and the server URL.
4. In **Authentication**, select **Sign in now**.
5. In **OAuth client**, select **Use Claude's published identity**.
6. Select **Add**.

Claude connects to the server from Anthropic's cloud.

**Cursor**

Add the server to `~/.cursor/mcp.json`, or to `.cursor/mcp.json` in
one project, with no headers:

```json mcp.json theme={null}
{
  "mcpServers": {
    "parable": {
      "url": "https://mcp.parable.work/mcp/workspaces/acme-corp"
    }
  }
}
```

Cursor runs the sign-in when the server asks for it.

**VS Code**

Add the server to `.vscode/mcp.json` in your workspace:

```json .vscode/mcp.json theme={null}
{
  "servers": {
    "parable": {
      "type": "http",
      "url": "https://mcp.parable.work/mcp/workspaces/acme-corp"
    }
  }
}
```

When the server starts, VS Code asks you to sign in.

**2. Allow access on the consent page**

The host opens the Workspace app in your browser. Sign in if the app
asks you to. The consent page then asks: "Allow ... to read data in your
Workspace?" It shows:

* Where the sign-in goes: "an application on this computer", or a host
  on the internet. A sign-in that goes to the internet, or that comes
  from a host that gave no name, has a caution.
* The name the host gives itself. Any program can choose any name, so
  allow only a sign-in that you started yourself just now.
* The Workspaces you may grant. Only Workspaces that allow external
  agents are on the list.

Choose the Workspace and select **Allow**. The host then holds access
for that Workspace and refreshes it without your help.

**3. Ask a question**

Ask the host a question about your data, such as "Which Provider tables
can you query in Parable?" In Claude Code, `/mcp` lists the server and
its tools.

A grant reads only (scope `data:read`). Its access token lasts one hour, and
the host refreshes it. A grant that the host does not use for 30 days
expires, and you sign in again.

To end a grant from Claude Code, run `claude mcp logout parable`. The
Workspace app has no list of grants. To refuse every grant in the Workspace
at once, turn **Allow external agents** off.

The server takes hosts that register as desktop applications. A host whose
sign-in returns to an address that is not on `localhost` and not on HTTPS
cannot sign in. If the sign-in fails with `invalid_redirect_uri` or
`invalid_client_metadata`, use an MCP token with that host.

## Use an MCP token

**1. Create an MCP token**

1. In the Workspace app, open **Protection → Access Tokens**.
2. Select **Create token**.
3. In **Use it for**, select **MCP**.
4. In **Name**, type where you use the token, such as `Claude Code on my laptop`.
5. In **Expires in**, select when the token stops working.
6. Select **Create token**.
7. Copy the token. The app shows it one time only.

You need a role that can query Provider data. **MCP** is available only
while the Workspace allows external agents. Keep the token in a secret
manager or an environment variable. The examples read it from
`PARABLE_MCP_TOKEN`.

**2. Add the server with the token**

The host sends the token in the `Authorization` header. Use the slug of
the Workspace where you created the token.

**Claude Code**

```bash theme={null}
claude mcp add --transport http parable-token \
  https://mcp.parable.work/mcp/workspaces/acme-corp \
  --header "Authorization: Bearer $PARABLE_MCP_TOKEN"
```

Use a different server name from your OAuth entry, such as
`parable-token`. Claude Code remembers a needed sign-in by server
name.

To share the server with your team in the project's `.mcp.json`, keep
the token out of the file. Each person sets `PARABLE_MCP_TOKEN` to
their own token:

```json .mcp.json theme={null}
{
  "mcpServers": {
    "parable-token": {
      "type": "http",
      "url": "https://mcp.parable.work/mcp/workspaces/acme-corp",
      "headers": {
        "Authorization": "Bearer ${PARABLE_MCP_TOKEN}"
      }
    }
  }
}
```

**Claude**

1. Open **Customize > Connectors**.
2. Select **Add custom connector**.
3. Type a name and the server URL.
4. In **Authentication**, select **No sign-in**.
5. In **Request headers**, select the header name `authorization`.
6. Type the value `Bearer ` followed by your token, with the space.
7. Mark the header **Required**, then select **Add**.

Claude offers **Request headers** to some organizations only.

> [!WARNING]
>
> On Claude Team and Enterprise plans, every member who uses an
> organization connector sends the same header. They all read as the
> token's owner, with that person's roles. Do not add a personal MCP
> token as an organization connector.

**Cursor**

```json mcp.json theme={null}
{
  "mcpServers": {
    "parable-token": {
      "url": "https://mcp.parable.work/mcp/workspaces/acme-corp",
      "headers": {
        "Authorization": "Bearer ${env:PARABLE_MCP_TOKEN}"
      }
    }
  }
}
```

Set `PARABLE_MCP_TOKEN` in your shell profile or system environment,
then restart Cursor.

**VS Code**

VS Code asks for the token the first time that the server starts, and
keeps it hidden:

```json .vscode/mcp.json theme={null}
{
  "inputs": [
    {
      "type": "promptString",
      "id": "parable-mcp-token",
      "description": "Parable MCP token",
      "password": true
    }
  ],
  "servers": {
    "parable-token": {
      "type": "http",
      "url": "https://mcp.parable.work/mcp/workspaces/acme-corp",
      "headers": {
        "Authorization": "Bearer ${input:parable-mcp-token}"
      }
    }
  }
}
```

**3. Check the connection**

To check the server without a host, list its tools:

```bash theme={null}
curl -s -X POST "https://mcp.parable.work/mcp/workspaces/acme-corp" \
  -H "Authorization: Bearer $PARABLE_MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'
```

The answer lists the tools that your roles allow. If
`query_provider_pool` is missing, your roles cannot query Provider data.
A Workspace administrator can give you the Provider Pools Reader role.

Only an MCP token works here. The server refuses a Parable token, a SQL token,
and a session from the app. When you stop using the server, remove it from
the host, because the host's configuration holds the token. Revoke the token
in **Protection → Access Tokens** if it may have leaked.

## How the server works

* **Transport.** The server speaks MCP `2025-11-25` over streamable HTTP. It
  takes `POST` only and answers other methods with `405`. It keeps no
  session and sends no `Mcp-Session-Id`, so every request carries its own
  `Authorization` header. A request can call `tools/list` without an
  `initialize` before it.
* **Identity.** Each request runs as the person, with the roles that the
  person holds in the Workspace at that moment. The server lists only the
  tools that those roles allow. It never forwards your credential.
* **Rate limit.** Each credential can make 120 requests a minute to each
  Workspace. More requests get `429` with `Retry-After`.
* **Revocation.** For up to 5 seconds after a revocation or a role change, the
  server can still list tools from its last answer. A tool call is refused.
* **Audit.** Parable keeps an audit record of each call that the server makes
  for you. The record names your host by its `X-Parable-Client` header, or by
  its `User-Agent` when that header is absent.
* **Browser origins.** A request with an `Origin` header must come from an
  origin that Parable allows. Desktop and command-line hosts send no
  `Origin`.
* **Sign-in metadata.** A `401` carries a `WWW-Authenticate` header that
  points to the protected-resource metadata at
  `https://mcp.parable.work/mcp/.well-known/oauth-protected-resource`. It
  names the authorization server, at the same host, and the one scope,
  `data:read`.
  The authorization server publishes its own metadata at
  `https://mcp.parable.work/.well-known/oauth-authorization-server`.

## Errors

| Status | Cause | Fix |
| - | - | - |
| `401` | No credential. Or a credential that the server does not accept: a revoked, expired, or mistyped MCP token, an expired or revoked grant, or a session from the app. The `WWW-Authenticate` header adds `error="invalid_token"`. | For a grant, sign in again. For an MCP token, create a new token. |
| `403` naming **External agent access**, or saying that personal access tokens are off | The Workspace does not allow external agents, or it turned personal access tokens off. | Ask a person who manages sign-in to turn the setting on. The same token works again, with no reconnect. |
| `403` saying what the endpoint takes | The token is a Parable token or a SQL token. | Create an MCP token. |
| `403` saying the token was created in another Workspace | The URL names a Workspace other than the token's, or the slug is wrong. | Use the slug of the token's Workspace. |
| `403` | You are not a member of the Workspace, the grant is for another Workspace, or a browser origin is not allowed. | Check the slug, then sign in again and choose this Workspace. |
| `413` | The request body is larger than 1 MiB. | Send a shorter request. |
| `429` | More than 120 requests in a minute from this credential to this Workspace. | Wait for the seconds in `Retry-After`. |
| `502` | The Workspace API did not answer. The credential is not the problem. | Try again later. |

A tool that fails returns an error result, not one of these statuses. See
[Tool errors](/mcp/tools.md#tool-errors).


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