MCP

Bag of words exposes an MCP (Model Context Protocol) server. Connect Claude, Cursor, or any MCP-compatible client to it, and that assistant can explore your data sources, run tracked queries, build dashboards, and call your agents’ tools — all as the signed-in user, under their existing BOW permissions.

This page is about BOW acting as an MCP server. To give BOW agents tools from an external MCP server (Notion, Linear, an internal service), see MCP Connections.

Endpoint

There is one MCP endpoint per deployment:

https://<YOUR_DOMAIN>/api/mcp

(https://<YOUR_DOMAIN>/mcp is served too.) It speaks MCP over Streamable HTTP. The organization comes from the credential, never from a header, so the same URL works for every organization on the deployment.

Two ways to connect

Every MCP request runs as a specific BOW user. There are two ways for that user to authenticate:

	Personal access token	OAuth app
Who sets it up	Each user, for themselves	An admin registers the app once; each user then signs in
What the client sends	`Authorization: Bearer bow_…`	`Authorization: Bearer bow_oauth_…`, obtained through sign-in and consent
Best for	Desktop and IDE clients with a config file (Claude Desktop, Cursor, Claude Code)	Hosted clients with a connector UI (Claude on the web, ChatGPT, internal apps), or orgs that want no long-lived keys in config files
Revoke	User deletes the token	User is removed from the org, or the admin deletes the app or changes its access surfaces

Either way the client acts as that user: they see only the agents and data sources they can access, tool policies apply as they do in the web app, and BOW rechecks org membership on every request. Removing someone from the organization stops their tokens immediately.

Enable the MCP server

The MCP server is on by default. Admins with manage_settings can turn it off for the whole organization under Settings → Channels → BOW MCP Server. When it is off, every MCP request returns 403 MCP integration is not enabled for this organization.

Option 1 — Personal access token (per user)

Each user generates their own token. Tokens are tied to that user’s account in the current organization.

Open your profile from the user menu and go to the MCP Server tab. (Admins also have MCP Server directly in the user menu.)
Select Generate Token. Copy it right away — it is shown only once.
Copy the Configuration snippet into your MCP client:

{
  "mcpServers": {
    "bagofwords": {
      "url": "https://<YOUR_DOMAIN>/api/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_TOKEN>"
      }
    }
  }
}

Where to put it:

Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows).
Cursor — your Cursor MCP settings (.cursor/mcp.json or the global MCP config).
Any other client — use the URL and the Authorization header shown above. X-API-Key: <YOUR_TOKEN> is accepted as well.

Regenerate Token creates an additional token; it does not revoke older ones. Use Manage tokens to see and delete your tokens. The same tokens also appear under Profile → API Keys, which you can use for programmatic access to the BOW API.

A token carries your access. Anyone holding it can query every data source you can. Delete tokens you no longer use.

Option 2 — OAuth app (admin-registered)

With OAuth, users never copy a token. The client sends them to BOW to sign in (local account or your SSO provider), they approve access, and the client receives a token scoped to MCP. BOW does not support dynamic client registration for its own MCP server — an admin must register each client app first.

Admin: register the app

You need manage_settings.

Open Settings → Channels → OAuth Apps and select Register app.
Name it after the client people will recognize, such as “Claude”.
Under Access surfaces, select MCP tools. Add BOW app only if the same client also calls the BOW API.
Add the client’s exact redirect URIs, one per line. For Claude on the web, use https://claude.ai/api/mcp/auth_callback; for other clients, use the callback URL their documentation gives you.
Optionally enable Trusted to skip the consent screen. Do this only for software your organization operates.
Save, then copy the Client ID and the Client secret (shown once) and share them with your users, or enter them in the client’s org-wide connector settings.

See OAuth Apps for the full option reference, secret rotation, and revocation.

User: connect the client

For Claude on the web, for example:

Go to Settings → Connectors → Add custom connector.
Enter https://<YOUR_DOMAIN>/api/mcp as the URL.
Under Advanced settings, enter the Client ID and Client secret from your admin.
Select Connect. Sign in to BOW if prompted, review the Authorize access screen (it requests MCP tools — “Use the MCP tool surface under your existing BOW permissions”), and select Approve.

Clients discover everything else automatically:

Metadata	URL
MCP protected resource	`https://<YOUR_DOMAIN>/.well-known/oauth-protected-resource`
Authorization server	`https://<YOUR_DOMAIN>/.well-known/oauth-authorization-server`

An unauthenticated request to the endpoint returns 401 with a WWW-Authenticate header that points the client to this metadata. The flow is OAuth 2.1 authorization code with PKCE (S256); refresh tokens rotate on each use. A token issued with only the mcp scope cannot call the BOW API, and an app-only token cannot call MCP.

Available tools

Tool	What it does
`create_report`	Starts an analysis session and returns a `report_id`. Attaches the data sources the user can access that are enabled for MCP.
`get_context`	Lists available data sources, tables, metadata resources, and agent tools. Supports pattern filtering.
`inspect_data`	Quick exploratory query that returns a small sample. Not saved.
`create_data`	Creates a tracked, reproducible query with a chart or table. Saved to the report, so it can be shared and added to dashboards. Returns result rows inline (see below).
`create_artifact`	Builds a dashboard, app or slide presentation. Apps can declare record, file and AI resources when Artifact resources is enabled.
`edit_artifact`	Applies targeted interface changes to an existing artifact.
`manage_artifact_resources`	Reads, creates, updates or deletes an artifact’s resource definitions and permissions. It manages configuration, not individual app records.
`list_agent_tools`	Lists the external tools (MCP connections and custom APIs) an agent can run, with their input schemas.
`execute_mcp`	Runs one of those agent tools — for example, searching Notion or creating a Jira issue — with the same tool policies as in the web app.
`send_email`	Emails the current user, and optionally other org members, with up to five attachments. Listed only when outbound email is configured.
`list_instructions`	Lists instructions from the current live build.
`create_instruction`	Creates an instruction. Admins publish immediately; other users submit for approval. Requires `manage_instructions`.
`delete_instruction`	Removes an instruction. Requires `manage_instructions`.

Tools the user lacks permission for are left out of tools/list. Clients that support MCP Apps also render charts and dashboards inline from create_data, create_artifact, and edit_artifact. For apps with saved data, enable Artifact resources in organization AI settings first; it is off by default. Use resource management for schemas and policies, and artifact editing for the interface. Authoring remains subject to report ownership and organization permissions. See Build apps with artifacts.

Controls

Rows returned by create_data — Settings → AI → MCP data preview rows (default 1,000, maximum 10,000). A client can ask for fewer rows, never more, and the org’s row-count limit still applies.
Per-agent availability — each agent can be switched off for the MCP channel in the Channels section of its settings. Agents switched off are not attached to reports created over MCP.
Agent tools — turning off MCP tools under Settings → AI also stops execute_mcp.
Instructions — instructions can be scoped to the MCP channel, so assistants get guidance that applies only there.

MCP reports

Every conversation from an MCP client is saved as a report under the user’s name, marked with an MCP icon (Created via MCP) in the Reports list.

Opening one shows the queries, visualizations, and dashboards the assistant created.

BOW does not see the external assistant’s own conversation. It records every tool call — what was queried, with which tool, and the results — but not the client’s prompts or model output beyond what was passed into a tool.

Example uses

In Claude: “What were our top 10 customers by revenue last month? Build a dashboard and email it to me.”
In Cursor: validate data assumptions while you write a feature, or check production patterns before writing a migration.
In any client: “Open a Linear issue for each failed load in yesterday’s pipeline run” — through an agent’s tools via list_agent_tools and execute_mcp.

Get Started

Work With Agents

Agents

Guides

Connect Any Data

Models

Observe and Govern

Channels

Open Source and Enterprise

Endpoint

Two ways to connect

Enable the MCP server

Option 1 — Personal access token (per user)

Option 2 — OAuth app (admin-registered)

Admin: register the app

User: connect the client

Available tools

Controls

MCP reports

Example uses

​Endpoint

​Two ways to connect

​Enable the MCP server

​Option 1 — Personal access token (per user)

​Option 2 — OAuth app (admin-registered)

​Admin: register the app

​User: connect the client

​Available tools

​Controls

​MCP reports

​Example uses

Endpoint

Two ways to connect

Enable the MCP server

Option 1 — Personal access token (per user)

Option 2 — OAuth app (admin-registered)

Admin: register the app

User: connect the client

Available tools

Controls

MCP reports

Example uses