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

# MCP

> Connect Claude, Cursor, ChatGPT, or any MCP client to Bag of words with a personal key or an admin-registered OAuth app

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.

<Note>
  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](/data-sources/mcp).
</Note>

## Endpoint

There is one MCP endpoint per deployment:

```text theme={null}
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`.

<img src="https://mintcdn.com/bagofwords/L9PU9JzfBV27xXcx/assets/media/mcp-integrations.png?fit=max&auto=format&n=L9PU9JzfBV27xXcx&q=85&s=f012e4fa9441838f531914c38a167eda" alt="MCP Server Integration Toggle" width="951" height="505" data-path="assets/media/mcp-integrations.png" />

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

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

```json theme={null}
{
  "mcpServers": {
    "bagofwords": {
      "url": "https://<YOUR_DOMAIN>/api/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_TOKEN>"
      }
    }
  }
}
```

<img src="https://mintcdn.com/bagofwords/L9PU9JzfBV27xXcx/assets/media/mcp-server.png?fit=max&auto=format&n=L9PU9JzfBV27xXcx&q=85&s=b757d7c7b241bdac20cfcd08c90770a7" alt="MCP Server Configuration" width="856" height="804" data-path="assets/media/mcp-server.png" />

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.

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

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

1. Open **Settings → Channels → OAuth Apps** and select **Register app**.
2. Name it after the client people will recognize, such as "Claude".
3. Under **Access surfaces**, select **MCP tools**. Add **BOW app** only if the same client also calls the BOW API.
4. 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.
5. Optionally enable **Trusted** to skip the consent screen. Do this only for software your organization operates.
6. 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](/channels/oauth-apps) for the full option reference, secret rotation, and revocation.

### User: connect the client

For Claude on the web, for example:

1. Go to **Settings → Connectors → Add custom connector**.
2. Enter `https://<YOUR_DOMAIN>/api/mcp` as the URL.
3. Under **Advanced settings**, enter the Client ID and Client secret from your admin.
4. 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](/using-bow/artifact-apps).

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

<img src="https://mintcdn.com/bagofwords/L9PU9JzfBV27xXcx/assets/media/mcp-reports.png?fit=max&auto=format&n=L9PU9JzfBV27xXcx&q=85&s=a47d9bfbd6d750e92f05f6f3ba0b5fc9" alt="MCP Reports" width="560" height="291" data-path="assets/media/mcp-reports.png" />

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

<img src="https://mintcdn.com/bagofwords/L9PU9JzfBV27xXcx/assets/media/mcp-report-view.png?fit=max&auto=format&n=L9PU9JzfBV27xXcx&q=85&s=793d4e31f9395110765c572ff31afb4b" alt="MCP Report View" width="1113" height="817" data-path="assets/media/mcp-report-view.png" />

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

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


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