# Board Paper Scraper: API & MCP Documentation

> Connect your AI tools to NHS board paper data.

## Quick Start

1. Get your API key from your account settings (Growth plan and above)
2. Pick your tool (Claude Code, Cursor, Windsurf, Codex, or REST API)
3. Paste the config below into your tool's settings
4. Replace YOUR_API_KEY with your actual key

## Claude Code

Add to ~/.claude/mcp.json:

```json
{
  "mcpServers": {
    "board-paper-sales": {
      "type": "streamable-http",
      "url": "https://boardpaperscraper.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

## Cursor

Add to Cursor MCP settings:

```json
{
  "mcpServers": {
    "board-paper-sales": {
      "url": "https://boardpaperscraper.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

## Windsurf

Add to Windsurf MCP configuration:

```json
{
  "mcpServers": {
    "board-paper-sales": {
      "serverUrl": "https://boardpaperscraper.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

## Codex

Add to ~/.codex/config.toml (or .codex/config.toml in your project):

```toml
[mcp_servers.board-paper-sales]
url = "https://boardpaperscraper.com/api/mcp"
bearer_token_env_var = "BOARD_PAPER_API_KEY"
```

Then set the environment variable:

```bash
export BOARD_PAPER_API_KEY=YOUR_API_KEY
```

## ChatGPT

ChatGPT doesn't support MCP natively yet. Use the REST API endpoints below.

## REST API Reference

Base URL: https://boardpaperscraper.com
Auth: Include `Authorization: Bearer YOUR_API_KEY` header or `?api_key=YOUR_API_KEY` query parameter on all requests.

### GET /api/v1/trusts/search

Search NHS trusts by name, region, type, or country.

Query parameters: q, type, region, country, page, per_page

```bash
curl "https://boardpaperscraper.com/api/v1/trusts/search?q=london&type=acute" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Response:

```json
{
  "data": [
    {
      "id": "uuid",
      "name": "Guy's and St Thomas' NHS Foundation Trust",
      "type": "acute",
      "region": "London",
      "country": "England",
      "website": "https://www.guysandstthomas.nhs.uk",
      "board_papers_count": 12,
      "latest_board_paper_date": "2026-01-15"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 1,
    "total_pages": 1
  }
}
```

### GET /api/v1/trusts/:id

Get detailed information about a specific NHS trust.

```bash
curl "https://boardpaperscraper.com/api/v1/trusts/TRUST_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Response:

```json
{
  "data": {
    "id": "uuid",
    "name": "Guy's and St Thomas' NHS Foundation Trust",
    "type": "acute",
    "region": "London",
    "country": "England",
    "website": "https://www.guysandstthomas.nhs.uk"
  }
}
```

### GET /api/v1/trusts/:id/board-papers

List all board papers for a trust, newest first.

```bash
curl "https://boardpaperscraper.com/api/v1/trusts/TRUST_ID/board-papers" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Response:

```json
{
  "data": [
    {
      "id": "uuid",
      "title": "Board Meeting Papers - January 2026",
      "date": "2026-01-15",
      "quarter": "Q4 2025/26",
      "board_paper_files": [
        {
          "id": "file-uuid",
          "file_name": "agenda.pdf",
          "file_size": 245000,
          "file_order": 1
        }
      ]
    }
  ]
}
```

### GET /api/v1/board-papers/:id

Get a specific board paper with file metadata.

```bash
curl "https://boardpaperscraper.com/api/v1/board-papers/PAPER_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Response:

```json
{
  "data": {
    "id": "uuid",
    "title": "Board Meeting Papers - January 2026",
    "date": "2026-01-15",
    "quarter": "Q4 2025/26",
    "trust_id": "trust-uuid",
    "board_paper_files": [
      {
        "id": "file-uuid",
        "file_name": "agenda.pdf",
        "file_size": 245000,
        "file_order": 1
      }
    ]
  }
}
```

### GET /api/v1/board-papers/:id/files/:fileId/download

Download a specific PDF file from a board paper. Returns the PDF directly.

```bash
curl "https://boardpaperscraper.com/api/v1/board-papers/PAPER_ID/files/FILE_ID/download" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### POST /api/mcp

MCP JSON-RPC endpoint. Supports tools/list and tools/call methods.

```bash
curl -X POST "https://boardpaperscraper.com/api/mcp" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
```

Available MCP tools:
- search_nhs_trusts: Search trusts by name, region, type, or country
- get_nhs_trust: Get detailed info about a specific trust
- list_board_papers: List all board papers for a trust
- get_board_paper: Get a board paper with file metadata
- download_board_paper_file: Get a download URL for a specific PDF file