Connect an MCP host

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 lists what the server offers. The server address for a Workspace is:

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

In the Workspace app, open Protection → Access Tokens.
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.

A host sends what it reads to its own model provider. Your Workspace’s AI processor settings do not cover that provider.

Add the server without a token

Follow the tab for your host.

Claude Code
Claude
Cursor
VS Code

claude mcp add --transport http parable \
  https://mcp.parable.work/mcp/workspaces/acme-corp

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

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

Open Customize > Connectors.
Select Add custom connector.
Type a name, such as Parable, and the server URL.
In Authentication, select Sign in now.
In OAuth client, select Use Claude’s published identity.
Select Add.

Claude connects to the server from Anthropic’s cloud.

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

mcp.json

{
  "mcpServers": {
    "parable": {
      "url": "https://mcp.parable.work/mcp/workspaces/acme-corp"
    }
  }
}

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

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

.vscode/mcp.json

{
  "servers": {
    "parable": {
      "type": "http",
      "url": "https://mcp.parable.work/mcp/workspaces/acme-corp"
    }
  }
}

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

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.

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

Create an MCP token

In the Workspace app, open Protection → Access Tokens.
Select Create token.
In Use it for, select MCP.
In Name, type where you use the token, such as Claude Code on my laptop.
In Expires in, select when the token stops working.
Select Create token.
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.

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
Claude
Cursor
VS Code

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:

.mcp.json

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

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

Claude offers Request headers to some organizations only.

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.

mcp.json

{
  "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 asks for the token the first time that the server starts, and keeps it hidden:

.vscode/mcp.json

{
  "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}"
      }
    }
  }
}

Check the connection

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

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.

Getting Started

MCP

SDKs

Providers

Parable Data Engine

Choose how the host signs in

Allow external agents

Use an MCP token

How the server works

Errors

​Choose how the host signs in

​Allow external agents

​Sign in with OAuth

​Use an MCP token

​How the server works

​Errors

Choose how the host signs in

Allow external agents

Sign in with OAuth

Use an MCP token

How the server works

Errors