vaquill-mcp

# vaquill-mcp

MCP server for [Vaquill](https://www.vaquill.ai) legal research API. Covers US federal and 50-state primary law: USC, CFR, state statutes and regulations, state and US constitutions, court rules, the Federal Register, executive orders, and agency guidance. Search primary law, resolve statutory citations, browse the hierarchy, and ground answers in official sources, all from your AI tools.

## Quick Start

### Prerequisites

Sign up at [vaquill.ai](https://www.vaquill.ai) to get your API key.

### Claude.ai (Web)

No installation needed. Add as a remote MCP server from **Customize > Connectors > Add custom connector**:

**Option A: Simple URL (API key in path)**

```
https://mcp.vaquill.ai/s/vq_key_your_key_here
```

**Option B: Bearer token (recommended)**

Open the **Request headers** section of the same dialog and add the credential there:

```
URL:            https://mcp.vaquill.ai/s/_
Header name:    Authorization
Header value:   Bearer vq_key_your_key_here
```

Claude sends the value exactly as you type it and adds no scheme of its own, so the value
field holds `Bearer vq_key_...` and **not** `Authorization: Bearer vq_key_...`.

Available on Claude Pro, Max, Team, and Enterprise plans. The Request headers section is in
beta and is enabled per account, it accepts a short allowlist of header names, and it holds at
most four. On Team and Enterprise an owner adds the connector under Organization settings first.

### Claude Desktop

Open the config file from **Settings > Developer > Edit Config**:

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "vaquill": {
      "command": "uvx",
      "args": ["vaquill-mcp"],
      "env": {
        "VAQUILL_API_KEY": "vq_key_your_key_here"
      }
    }
  }
}
```

For **Indian legislation**, add `--jurisdiction IN`. One process serves one
corpus, so run two entries if you want both:

```json
{
  "mcpServers": {
    "vaquill": {
      "command": "uvx",
      "args": ["vaquill-mcp"],
      "env": { "VAQUILL_API_KEY": "vq_key_your_key_here" }
    },
    "vaquill-india": {
      "command": "uvx",
      "args": ["vaquill-mcp", "--jurisdiction", "IN"],
      "env": { "VAQUILL_API_KEY": "vq_key_your_key_here" }
    }
  }
}
```

Quit Claude completely and reopen it. It does not reload the file.

### Claude Code

**Remote (no install):**

```bash
claude mcp add --transport http --scope user vaquill \
  https://mcp.vaquill.ai/s/_ \
  --header "Authorization: Bearer vq_key_your_key_here"
```

**Local (via uvx):**

```bash
claude mcp add --scope user vaquill -e VAQUILL_API_KEY=vq_key_your_key_here \
  -- uvx vaquill-mcp
```

`--scope user` registers the server for every project; the default is the current directory
only. `-e` stores the key with the registration, so it survives Claude Code being launched
from an IDE, which an `export` in your shell profile does not. Both `--header` and `-e` are
variadic, so they have to come after the server name.

### Cursor

Edit `~/.cursor/mcp.json` for every project, or `.cursor/mcp.json` for one.

**Remote:**

```json
{
  "mcpServers": {
    "vaquill": {
      "url": "https://mcp.vaquill.ai/s/_",
      "headers": {
        "Authorization": "Bearer vq_key_your_key_here"
      }
    }
  }
}
```

**Local (via uvx):**

```json
{
  "mcpServers": {
    "vaquill": {
      "command": "uvx",
      "args": ["vaquill-mcp"],
      "env": {
        "VAQUILL_API_KEY": "vq_key_your_key_here"
      }
    }
  }
}
```

### VS Code (Copilot)

Add to `.vscode/mcp.json`. For every project instead of one, run the
**MCP: Open User Configuration** command and use the same shape there.

**Remote:**

```json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "vaquill-authorization",
      "description": "Authorization header value",
      "password": true
    }
  ],
  "servers": {
    "vaquill": {
      "type": "http",
      "url": "https://mcp.vaquill.ai/s/_",
      "headers": {
        "Authorization": "${input:vaquill-authorization}"
      }
    }
  }
}
```

The credential goes in a prompt rather than in the file, so the file is safe to commit. VS Code
asks for it on first start and remembers it. Restart the server after saving, or the tools will
not appear.

**Local (via uvx):**

```json
{
  "servers": {
    "vaquill": {
      "type": "stdio",
      "command": "uvx",
      "args": ["vaquill-mcp"],
      "env": {
        "VAQUILL_API_KEY": "vq_key_your_key_here"
      }
    }
  }
}
```

### Windsurf

Add to `~/.codeium/windsurf/mcp_config.json`.

**Remote:**

```json
{
  "mcpServers": {
    "vaquill": {
      "serverUrl": "https://mcp.vaquill.ai/s/_",
      "headers": {
        "Authorization": "Bearer vq_key_your_key_here"
      }
    }
  }
}
```

Windsurf uses `serverUrl` for a remote server, not `url`, and interpolates `${env:VAR}` if you
would rather read the credential from the environment.

**Local (via uvx):**

```json
{
  "mcpServers": {
    "vaquill": {
      "command": "uvx",
      "args": ["vaquill-mcp"],
      "env": {
        "VAQUILL_API_KEY": "vq_key_your_key_here"
      }
    }
  }
}
```

## Available Tools

Tools are generated from the live Vaquill API's OpenAPI spec at startup, so the
set always matches the current API. For the **authoritative, up-to-date list and
per-call credit costs**, run the free `get_pricing` tool or inspect your MCP
client's tool list. The main groups (representative tools shown):

### US statutes & regulations

USC, CFR, all 50 state codes, constitutions, state court rules, the Federal
Register, and agency guidance.

| Tool | Description |
|------|-------------|
| `search_us_statutes` | Hybrid semantic + keyword search; filter by `corpusType`, `state`, `titleNumber`, `chapter`, year, and more. |
| `get_us_statute_section` | Section metadata by `actId` (citation, hierarchy, official-source links). |
| `get_us_statute_section_text` | Full HTML + plain text of a section. |
| `get_sections_batch` | Metadata for up to 50 sections in one call. |
| `resolve_statute_citation` | Resolve a Bluebook citation (e.g. `42 U.S.C. § 1983`) straight to its section. |
| `list_statute_divisions` | Browse the statutory hierarchy one level at a time. |
| `list_statutes_coverage` | Self-describing coverage matrix: which corpora exist in which jurisdiction. |

### Reading a section in context

| Tool | Description |
|------|-------------|
| `get_section_neighbors` | The sections immediately before and after, in statutory order. |
| `get_section_definitions` | The defined terms that govern a section, from its chapter's definitions section. |
| `get_section_cited_by` | Which USC/CFR sections cross-reference this one (the inverse of `crossReferences`). |
| `get_section_cross_state` | Provisions in other states addressing the same subject, ranked by similarity. |
| `get_section_changes` | What our refreshes observed changing on this section over time. |

### Law change alerts

Subscribe to a corpus source and get a webhook or email when it changes.
Subscribing, polling and inspecting deliveries are all free; only
`get_watch_change_diff` is metered, because it is the only one that returns
section text.

| Tool | Description |
|------|-------------|
| `list_boards` | The watchable sources (Federal Register, CFR, a state's statutes, ...). |
| `create_watch` | Subscribe to a board via webhook (HMAC-SHA256 signed) or email. |
| `list_watches`, `update_watch`, `delete_watch` | Manage your subscriptions. |
| `test_watch` | Send a synthetic delivery to verify signing, auth and reachability. |
| `list_watch_changes` | What changed on a watched source. Metadata only, and safe to poll. |
| `get_watch_change_diff` | Before/after text for one change, as whole documents. |
| `list_watch_deliveries` | Per-attempt webhook delivery log (90 days). |

### Utility

| Tool | Description |
|------|-------------|
| `get_pricing` | Live API credit pricing (free, no auth). |
| `search` | Generic one-string corpus search returning `{id, title, url}`. |
| `fetch` | Generic one-string retrieval returning `{id, title, text, url, metadata}`. |

`search` and `fetch` exist because ChatGPT's deep research and company-knowledge
connectors match a corpus server by those exact names and their single-string
signature, and refuse to work without them. They are thin wrappers over the
typed tools above, which any client that can call them should prefer: the typed
ones filter by jurisdiction, corpus, date and status, and these two do not.
`fetch` is deliberately lenient about its `id`, accepting an act_id, a citation
URL, a bare path, or a Bluebook citation such as `42 U.S.C. 1983`.

### Resources and prompts

This server is not only tools. An MCP server generated from an OpenAPI document
publishes one tool per endpoint and nothing else; these two primitives are where
the knowledge that is not in the API lives, and neither costs anything in the
per-turn tool budget.

**Resources** (read, don't call):

| Resource | Contents |
|----------|----------|
| `vaquill://guide` | How to use the corpus correctly: identifier rules, what "still good law" actually means here, what an empty change list does and does not tell you, and where the cost is. Not backed by any endpoint. |
| `vaquill://us/coverage` | Coverage matrix: every corpusType and its per-jurisdiction counts. Free. |
| `vaquill://in/filters` | The filter vocabulary the India corpus actually holds. Free. |
| `vaquill://pricing` | Live credit pricing. Free. |

**Prompts** (workflows, with the traps built in):

| Prompt | What it encodes |
|--------|-----------------|
| `good_law_check(citation)` | `actStatus` vs `goodLawStatus` vs `amendmentHistory`, and why `unknown` means unchecked rather than current. |
| `fifty_state_survey(topic, states)` | Check coverage first, so "no such law" and "not in our corpus" are never conflated. |
| `whats_changed(si