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

# MCP server

> Connect AI agents to your Weave data using the Model Context Protocol

The Model Context Protocol (MCP) server provides a standardized interface that allows any compatible AI model or agent to access your Weave data in a simple and secure way.

Connect to the Weave MCP server natively in Claude, Cursor, and other clients to query engineering metrics, explore team performance, and analyze your development data through natural language.

## What you can do

The Weave MCP server enables AI agents to:

* **Query metrics** — Get aggregated metrics like code output, PR cycle time, review turnaround, and more
* **Drill down into data** — See the actual PRs, tasks, and reviews behind each metric
* **Explore teams and accounts** — List team structures and individual contributors
* **Analyze AI skill usage** — See which agent skills (reusable workflows like `graphite-pr`) your team runs, trends over time, and per-engineer breakdowns
* **Filter and group** — Slice data by team, repository, time period, PR type, and AI coding tool
* **Query in your timezone** — Interpret date boundaries and sub-day time windows (for example, PRs merged between 4pm and 10pm Pacific) in a named IANA timezone

## Setup instructions

The Weave MCP server uses **OAuth 2.1**. Provide the MCP URL in your client; on first connect it opens a browser so you can sign in to Weave and authorize access. Tokens are cached and refreshed automatically.

### Headless jobs

Automated jobs can use the OAuth 2.1 `client_credentials` grant without a browser or localhost callback. An organization admin creates a service client with the `create_mcp_service_client` GraphQL mutation. The mutation uses the admin's current organization context, and the returned secret is shown only once.

Run the mutation from an authenticated GraphQL client against `https://app.workweave.ai/api/graphql`:

```graphql theme={null}
mutation CreateMCPServiceClient($name: String!) {
  create_mcp_service_client(name: $name) {
    client {
      client_id
      name
      created_at
    }
    client_secret
  }
}
```

Example response:

```json theme={null}
{
  "data": {
    "create_mcp_service_client": {
      "client": {
        "client_id": "mcp_3LKQhvGUcADgqoEM3bh6pslE",
        "name": "weekly-output-watch",
        "created_at": "2026-09-21T18:00:00Z"
      },
      "client_secret": "mcpsec_..."
    }
  }
}
```

Store both values in the job's secret manager. Never log `client_secret`; it cannot be recovered after this response.

Request a short-lived access token with HTTP Basic authentication:

```bash theme={null}
token_response=$(curl --fail-with-body -sS \
  -u "$WEAVE_MCP_CLIENT_ID:$WEAVE_MCP_CLIENT_SECRET" \
  -d grant_type=client_credentials \
  -d scope=mcp:tools \
  https://app.workweave.ai/public/token)
export WEAVE_MCP_ACCESS_TOKEN="$(jq -r .access_token <<<"$token_response")"
```

The response contains a Bearer `access_token`, an `expires_in` value, and no refresh token. Use the access token against the MCP endpoint (this example asks the server for its tool list):

```bash theme={null}
curl --fail-with-body -sS \
  -H "Authorization: Bearer $WEAVE_MCP_ACCESS_TOKEN" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
  https://app.workweave.ai/public/mcp
```

Existing read-only `wkey_…` API keys can also be exchanged without provisioning a service client. Send the key as `X-API-Key` to the same token endpoint with `grant_type=client_credentials`:

```bash theme={null}
curl --fail-with-body -sS \
  -H "X-API-Key: $WEAVE_API_KEY" \
  -d grant_type=client_credentials \
  -d scope=mcp:tools \
  https://app.workweave.ai/public/token
```

To revoke a provisioned client, an organization admin can run:

```graphql theme={null}
mutation DeleteMCPServiceClient($clientId: ID!) {
  delete_mcp_service_client(client_id: $clientId)
}
```

Deleting a service client invalidates its credentials and tokens. The `mcp_service_clients` field on `Organization` lists the active clients for administrators.

In the Weave app, organization admins can also find a copyable MCP URL and starter snippets for Cursor and Claude Code under **Organization settings** → **Exports** (above the CSV export section).

### Cursor

To add the MCP to Cursor, add the following to your `.cursor/mcp.json` file:

```json theme={null}
{
  "mcpServers": {
    "weave": {
      "type": "http",
      "url": "https://app.workweave.ai/public/mcp"
    }
  }
}
```

On first connection, Cursor will open a browser window for you to log in to Weave and authorize access.

### Claude Code

The easiest way is to use the Claude Code CLI:

```bash theme={null}
claude mcp add --transport http weave https://app.workweave.ai/public/mcp
```

Or add it manually to one of these files, depending on scope (see [Connect Claude Code to MCP](https://code.claude.com/docs/en/mcp)):

* `.mcp.json` at the root of your project — project scope; shared with your team via git
* `~/.claude.json` — local scope (what `claude mcp add` uses by default) and user scope (`claude mcp add --scope user`; available across all projects). This is separate from other Claude Code settings under `~/.claude/settings.json`.

Example for a project-scoped `.mcp.json` file:

```json theme={null}
{
  "mcpServers": {
    "weave": {
      "type": "http",
      "url": "https://app.workweave.ai/public/mcp"
    }
  }
}
```

On first use, a browser window will open for Weave login. After authorizing, the token is cached and refreshed automatically.

### Claude Desktop

The exact menu path depends on your Claude plan. See Anthropic's [custom connectors guide](https://support.claude.com/en/articles/11175166) for the latest instructions.

<Note>
  Custom connectors are configured through your Claude account, so the steps are
  the same in Claude Desktop and `claude.ai`. Make sure you're on the latest
  version of Claude Desktop.
</Note>

**For Free, Pro, and Max plans:**

1. Go to **Settings > Connectors** (in `claude.ai`, this is also accessible as **Customize > Connectors**).
2. Click the **+** button next to **Connectors**, then select **"Add custom connector"**.
3. Set the name to **Weave** and the remote MCP server URL to `https://app.workweave.ai/public/mcp`, then click **Add**.
4. Find **Weave** in your list of connectors and click **Connect**.
5. In the browser window that pops up, sign in to Weave and click **Authorize**.

**For Team and Enterprise plans:**

An Owner or Primary Owner needs to add the connector to the organization first; members then connect to it individually.

*Owner steps:*

1. Go to **Organization settings > Connectors**.
2. Click the **Add** button.
3. Hover over **Custom**, then select **Web**.
4. Enter the name **Weave** and the remote MCP server URL `https://app.workweave.ai/public/mcp`.
5. Click **Add**.

*Member steps (after the Owner has added it):*

1. Go to **Settings > Connectors** (or **Customize > Connectors**).
2. Find **Weave** in the list (it will have a "Custom" label) and click **Connect**.
3. In the browser window that pops up, sign in to Weave and click **Authorize**.

<Note>
  Claude reaches custom connectors from Anthropic's cloud (not from your local
  machine), even when you're using Claude Desktop. The Weave MCP server is
  publicly reachable, so this works out of the box — no firewall changes needed.
</Note>

### Visual Studio Code

1. Press `CTRL/CMD + SHIFT + P` and search for **MCP: Add Server**
2. Select **HTTP** and enter the URL: `https://app.workweave.ai/public/mcp`
3. Enter the name **Weave** and hit enter
4. A browser window will open for Weave login on first connection

### Windsurf

1. Press `CTRL/CMD + ,` to open Windsurf settings
2. Scroll to **Cascade > MCP servers**
3. Select **Add Server > Add custom server**
4. Add the following:

```json theme={null}
{
  "mcpServers": {
    "weave": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://app.workweave.ai/public/mcp"
      ]
    }
  }
}
```

### Other clients

Many AI tools now support MCP servers. Configure them with:

* **URL**: `https://app.workweave.ai/public/mcp`
* **Authentication**: OAuth 2.1 (automatic)

## Available tools

The MCP server provides tools for querying your Weave data, including:

| Tool | Description |
| - | - |
| **get\_metric\_overview** | Get aggregated metrics with trends, benchmarks, and groupings. Optional `timezone` (IANA, e.g. `America/Los_Angeles`) sets how date boundaries are interpreted. |
| **search\_documentation** | Search Weave product documentation for how-to guidance, metric definitions, and feature help. |
| **get\_documentation** | Retrieve the full content of a specific Weave documentation page by its path or URL. |
| **get\_metric\_drill\_down** | Get individual records (PRs, tasks, reviews) behind a metric. Supports optional `timezone` and sub-day time-of-day windows via naive local `start_time`/`end_time` (e.g. `2026-06-11T16:22`). For PR metrics, sub-day filtering uses **merge time**, not opened or committed time. |
| **resolve\_entities** | Find accounts, teams, repositories, or tags by fuzzy name search, batch ID lookup, or list all entities of a type. Use this to resolve names before filtering other tools. |
| **search\_prs** | Search pull requests by title or description. Returns PR IDs you can pass to **get\_pr\_details**. |
| **get\_pr\_details** | Get metadata for a pull request by ID (from **search\_prs** or drill-down). Does not include the code diff. |
| **get\_skill\_usage** | Get skill (agent workflow) invocation counts over time, by skill and source. Pass `names_only=true` to list distinct skill names for filtering. |
| **get\_skill\_usage\_drilldown** | Get per-(account, day) rows behind a single skill. Pass `include_session_stats=true` for per-skill session stats (completion rate, lines added, cost, prompts). |
| **research\_overview** | Get a full metrics snapshot for an account, team, or repository. |
| **get\_anomalies\_and\_trends** | Get active anomalies and metric trends for your organization. |
| **search\_tasks** | Search tasks by title and description. Returns task IDs you can pass to **get\_task\_details**. |
| **get\_task\_details** | Get details for specific tasks by ID. |
| **get\_engineer\_profiles** | Get engineer profiles with component expertise, current workload, and documentation activity. |
| **get\_user\_activity** | Get one person's activity timeline over a time range. |
| **get\_milestones** | Get event milestones for your organization. |
| **get\_rd\_breakdown** | Get the R\&D category mix of PRs and code output per month or per team. Excludes salary and wage data. |
| **get\_rd\_breakdown\_drilldown** | Get the PRs or Jira items in one R\&D category. |
| **get\_tool\_call\_usage** | Get how often your AI coding assistants call each tool (for example `Bash`, `Read`, or MCP tools), over time and by source. |

## Example queries

Once connected, you can ask your AI agent questions like:

* "What was our team's code output last week?"
* "Show me the PRs with the longest cycle time this month"
* "Compare AI-assisted vs manual code output for the backend team"
* "Show code output grouped by Linear initiative last month"
* "Who has the fastest code review turnaround?"
* "List all PRs merged to main this quarter, grouped by type"
* "Which agent skills did the team use most last month?"
* "Show me who ran the graphite-pr skill and how often"
* "Which PRs merged between 4:22pm and 10:43pm Pacific on June 11?"
* "Read the full API documentation at /api-reference/metrics/get-metrics.md"

## Timezone and time-of-day filtering

`get_metric_drill_down` and `get_metric_overview` accept an optional `timezone` parameter (IANA name, e.g. `America/Los_Angeles`). It controls how date boundaries are interpreted for the request.

For drill-down, you can also pass a **sub-day time window** by including a clock time in `start_time` and `end_time` as naive local datetimes (for example, `2026-06-11T16:22` with no `Z` or offset). When both bounds carry a non-midnight clock time, rows are filtered to those whose **primary timestamp** falls inside that window, localized in `timezone`:

* **PR metrics** — primary timestamp is **merge time** (`Merged at`), not when the PR was opened or committed
* **Date-only requests** (no clock time) keep standard calendar-day behavior

The applied window is echoed back in `metadata.time_of_day_filter` on drill-down responses so agents can confirm which timestamp and timezone were used.

`timezone` is auto-filled from the user's browser timezone when available. Override it only when the user names a different timezone.

## Authentication

### OAuth 2.1

The MCP server uses OAuth 2.1. Your client opens a browser for you to log in to Weave and authorize access. After authorization, the client receives a token that is automatically refreshed.

For automated jobs that cannot open a browser, use the [`client_credentials` grant](#headless-jobs) instead.

* No long-lived secrets to paste into config files
* Works with clients that don't support environment variable substitution
* Tokens are scoped to your account and organization

<Note>
  OAuth tokens have the same permissions as the user who authorizes them. Team members can only access data for teams they belong to.
</Note>

## FAQ

<AccordionGroup>
  <Accordion title="Which AI assistants support the Weave MCP?">
    Any AI tool that supports the Model Context Protocol can connect to Weave. This includes Claude, Cursor, VS Code with Copilot, Windsurf, and many others. Check your tool's documentation for MCP support.
  </Accordion>

  <Accordion title="What data can the MCP access?">
    The MCP server provides read-only access to your Weave metrics, teams, and
    accounts. It cannot modify any data or settings.
  </Accordion>

  <Accordion title="How do I troubleshoot connection issues?">
    1. Check the MCP server URL is correct: `https://app.workweave.ai/public/mcp`
    2. Ensure your client supports HTTP-based MCP servers
    3. Try clearing cached OAuth tokens and re-authenticating (for example delete mcp-remote's token cache: on macOS or Linux that is usually `~/.mcp-auth`, or the directory in `MCP_REMOTE_CONFIG_DIR` if you use a custom location, then restart the client)
  </Accordion>

  <Accordion title="Can I use the MCP with multiple Weave organizations?">
    OAuth ties the MCP session to the Weave account you sign in with. To use a different organization, sign in to Weave as a user who belongs to that org (or switch org in the app), then re-authorize the MCP connection so the token matches the org you need. You can also add multiple MCP server entries in your client and authorize each one after signing into the right account in the browser.
  </Accordion>
</AccordionGroup>


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