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

# Connect an AI assistant to your data

> The Scoutworks MCP server lets Claude, Cursor, VS Code and other assistants read your group’s data with your API key.

The Scoutworks **MCP server** lets an AI assistant read your group’s data while it works. Ask it a question in plain words, for example “Which Cubs are going to summer camp, and who still needs a parent’s phone number?”, and it reads the answer from Scoutworks.

```text MCP server address theme={null}
https://mcp.scoutworks.app/mcp
```

The server shows exactly what the API shows, and nothing more. Each tool is one read of the API, made with your own key. The key’s scopes, its group and its [rate limit](https://developers.scoutworks.app/guides/rate-limits.md) all apply. The server cannot change any data, and it keeps nothing between requests.

> [!WARNING]
>
> An assistant sends what it reads to its AI provider (for example Anthropic or OpenAI). With `members.contacts:read`, that includes children’s dates of birth and home addresses, and parents’ emails and phone numbers. Create a separate key for the assistant, and give it only the scopes it needs. See [Keys and scopes](https://developers.scoutworks.app/guides/authentication.md#scopes).

## Before you start

1. A group admin turns on the API in **Settings → Beta Programme**.
2. The group admin creates a key in **Settings → Integrations → API keys**. Give it a name such as “Claude”, so you know which key to revoke later.
3. Copy the key. It starts with `sw_live_`.

The server reads the live Scoutworks only. The [sandbox key](https://developers.scoutworks.app/guides/sandbox.md) does not work with it.

## Connect your assistant

Every request needs the key in the `Authorization` header. Replace `sw_live_…` with your key.

> [tab] Claude Code
>
> Run this in a terminal:
>
> ```bash theme={null}
> claude mcp add --transport http scoutworks https://mcp.scoutworks.app/mcp \
>   --header "Authorization: Bearer sw_live_…"
> ```
>
> The key goes into your own Claude Code settings. Do not add the server to a project’s shared `.mcp.json` with the key in it.

> [tab] Claude Desktop
>
> Claude Desktop adds a remote server through a small bridge, `mcp-remote`. You need [Node.js](https://nodejs.org) installed. Open **Settings → Developer → Edit Config**, and add this to `claude_desktop_config.json`:
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "scoutworks": {
>       "command": "npx",
>       "args": [
>         "-y",
>         "mcp-remote",
>         "https://mcp.scoutworks.app/mcp",
>         "--header",
>         "Authorization:${SCOUTWORKS_AUTH}"
>       ],
>       "env": { "SCOUTWORKS_AUTH": "Bearer sw_live_…" }
>     }
>   }
> }
> ```
>
> Restart Claude Desktop.

> [tab] Cursor
>
> Add this to `~/.cursor/mcp.json`:
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "scoutworks": {
>       "url": "https://mcp.scoutworks.app/mcp",
>       "headers": { "Authorization": "Bearer sw_live_…" }
>     }
>   }
> }
> ```

> [tab] VS Code
>
> Add this to `.vscode/mcp.json`. VS Code asks for the key the first time and keeps it in its secret store, so the file holds no key:
>
> ```json theme={null}
> {
>   "inputs": [
>     {
>       "type": "promptString",
>       "id": "scoutworks-key",
>       "description": "Scoutworks API key",
>       "password": true
>     }
>   ],
>   "servers": {
>     "scoutworks": {
>       "type": "http",
>       "url": "https://mcp.scoutworks.app/mcp",
>       "headers": { "Authorization": "Bearer ${input:scoutworks-key}" }
>     }
>   }
> }
> ```

**Claude.ai and ChatGPT** connect by sign-in, not by key. That is not ready yet. We will add it to this page and the [changelog](https://developers.scoutworks.app/changelog.md) when it is.

## The tools

There is one tool for each read endpoint in the [API reference](https://developers.scoutworks.app/api-reference/introduction.md). The MCP server only reads: it has no tool for an endpoint that changes data, such as `POST /tasks`. The assistant sees only the tools that your key’s scopes open, so a group key never sees the district tools.

| Tool | What it reads | Scope |
| - | - | - |
| `get_me` | The group and key this API key belongs to | none |
| `list_members` | Members | `members:read` |
| `list_sections` | Sections and units | `members:read` |
| `list_events` | Events | `events:read` |
| `list_event_attendees` | Who is going to an event | `events:read` |
| `list_badge_records` | Badge progress and awards | `badges:read` |
| `list_badge_catalogue` | The badges your group can award | `badges:read` |
| `list_waiting_list` | The waiting list | `waiting-list:read` |
| `list_task_boards` | Task boards, with their columns and labels | `tasks:read` |
| `list_tasks` | Tasks on those boards (never their descriptions) | `tasks:read` |
| `list_node_descendants` | The groups and nodes below yours | `nodes:structure:read` |
| `list_node_metrics` | The nightly totals for your area | `nodes:metrics:read` |

Each tool takes the same parameters as its endpoint, and returns the same JSON. A list is [paged](https://developers.scoutworks.app/guides/pagination.md): the assistant passes `nextCursor` back as `cursor` to read the next page. When the API adds a read endpoint, it becomes a tool here too.

## Limits and errors

* Each tool call is one API request, and counts against your key’s 120 requests a minute. When the assistant lists the tools, that is one more request.
* A long question can take many pages. If the assistant reaches the limit, the tool returns the `rate_limited` error, and the assistant can wait and try again.
* When the API refuses a call, the tool returns the API’s [error message](https://developers.scoutworks.app/guides/errors.md) and a request ID. Give us the request ID if you [contact us](https://scoutworks.app/contact) about it.
* A missing or revoked key gets `401`. Check the key in **Settings → Integrations → API keys**.

## Stop an assistant reading your data

Revoke its key in **Settings → Integrations → API keys**. The next tool call fails at once.

> [!NOTE]
>
> This is not the same as the [documentation MCP server](https://developers.scoutworks.app/tools/ai-assistants.md#3-connect-it-as-an-mcp-server) at `developers.scoutworks.app/mcp`. That one searches these docs and needs no key. This one reads your group’s data.


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