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

# Vaquill MCP Server

> US statutes MCP for Claude, Cursor, VS Code, and Windsurf. USC + CFR + 50-state statute codes.

The Vaquill MCP server gives any [Model Context Protocol](https://modelcontextprotocol.io) client - Claude.ai, Claude Desktop, Claude Code, Cursor, VS Code, Windsurf - direct access to the Vaquill statutes API. It covers **US federal and 50-state statutes** (the US Code, the CFR, and all 50 state statute codes). Source: [github.com/Vaquill-AI/vaquill-mcp](https://github.com/Vaquill-AI/vaquill-mcp).

<CardGroup cols={3}>
  <Card title="GitHub" icon="github" href="https://github.com/Vaquill-AI/vaquill-mcp">
    Source code and issues
  </Card>

  <Card title="PyPI" icon="python" href="https://pypi.org/project/vaquill-mcp/">
    `uvx vaquill-mcp`
  </Card>

  <Card title="Hosted endpoint" icon="cloud" href="https://mcp.vaquill.ai">
    `https://mcp.vaquill.ai`
  </Card>
</CardGroup>

## Quickstart

The fastest path is the hosted remote MCP on Claude.ai web - no install, no local Python, no config files.

<Prompt description="**Install Vaquill MCP in Claude Code** with one paste. Replaces a manual config edit." icon="rocket" iconType="solid" actions={["copy"]}>
  Install the Vaquill MCP server in Claude Code using my API key.

  1. Run `claude mcp add-json vaquill '{"type":"http","url":"https://mcp.vaquill.ai/s/_","headers":{"Authorization":"Bearer vq_key_REPLACE_ME"}}'` to register the remote MCP.
  2. Confirm the server is wired by running `claude mcp list` and looking for `vaquill`.
  3. Then try a smoke test prompt like *"Use Vaquill to pull the full text of 18 USC 1343 and summarize it in two sentences."*

  If anything fails, show me the exact error and the output of `claude mcp list`.
</Prompt>

<Steps>
  <Step title="Get an API key">
    Generate a `vq_key_...` token from your [dashboard settings](https://app.vaquill.ai/settings). See [Authentication](/docs/api-guide/authentication).
  </Step>

  <Step title="Open Claude.ai Settings > Integrations">
    Click **Add a connector** and pick **Custom MCP server**.
  </Step>

  <Step title="Paste the URL">
    Use either the path-token form:

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

    Or, if your client supports auth headers, use the bearer-token form:

    ```
    URL:   https://mcp.vaquill.ai/s/_
    Token: vq_key_your_key_here
    ```
  </Step>

  <Step title="Look up a statute">
    Try: *"What does 17 CFR 240.10b-5 say about insider trading?"* - Claude will call `search_us_statutes` and pull the section text.
  </Step>
</Steps>

<Info>
  Remote MCP connectors are available on Claude Pro, Max, Team, and Enterprise plans.
</Info>

## Client setup

Pick your client below. All configs accept the same set of environment variables - see [Environment variables](#environment-variables).

<CodeGroup>
  ```json Claude Desktop theme={"theme":"github-dark"}
  // ~/Library/Application Support/Claude/claude_desktop_config.json  (macOS)
  // %APPDATA%\Claude\claude_desktop_config.json                       (Windows)
  {
    "mcpServers": {
      "vaquill": {
        "command": "uvx",
        "args": ["vaquill-mcp"],
        "env": {
          "VAQUILL_API_KEY": "vq_key_your_key_here"
        }
      }
    }
  }
  ```

  ```bash Claude Code (remote) theme={"theme":"github-dark"}
  claude mcp add-json vaquill '{
    "type": "http",
    "url": "https://mcp.vaquill.ai/s/_",
    "headers": { "Authorization": "Bearer vq_key_your_key_here" }
  }'
  ```

  ```bash Claude Code (local) theme={"theme":"github-dark"}
  claude mcp add vaquill -- uvx vaquill-mcp
  export VAQUILL_API_KEY=vq_key_your_key_here
  ```

  ```json Cursor theme={"theme":"github-dark"}
  // Settings > MCP Servers
  {
    "mcpServers": {
      "vaquill": {
        "command": "uvx",
        "args": ["vaquill-mcp"],
        "env": {
          "VAQUILL_API_KEY": "vq_key_your_key_here"
        }
      }
    }
  }
  ```

  ```json VS Code (Copilot) theme={"theme":"github-dark"}
  // .vscode/settings.json
  {
    "mcp": {
      "servers": {
        "vaquill": {
          "command": "uvx",
          "args": ["vaquill-mcp"],
          "env": {
            "VAQUILL_API_KEY": "vq_key_your_key_here"
          }
        }
      }
    }
  }
  ```

  ```json Windsurf theme={"theme":"github-dark"}
  // ~/.windsurf/settings.json
  {
    "mcpServers": {
      "vaquill": {
        "command": "uvx",
        "args": ["vaquill-mcp"],
        "env": {
          "VAQUILL_API_KEY": "vq_key_your_key_here"
        }
      }
    }
  }
  ```
</CodeGroup>

<Tip>
  The `uvx` runner requires Python 3.10+ and [uv](https://docs.astral.sh/uv/) on `PATH`. `uvx vaquill-mcp` downloads and executes the package in an isolated env on first run; subsequent runs are instant.
</Tip>

## Tools

The server exposes statute tools across three categories.

### General

| Tool          | Description                                       | Credits |
| ------------- | ------------------------------------------------- | ------- |
| `get_pricing` | Get current API credit pricing. No auth required. | Free    |

### US law (USC + CFR)

| Tool                          | Description                                                                                                                          | Credits |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ------- |
| `search_us_statutes`          | Semantic search across the United States Code (USC) and Code of Federal Regulations (CFR). Filter by `corpusType` and `titleNumber`. | 2       |
| `get_us_statute_section`      | Metadata for a specific USC / CFR section by `act_id` - citation, title hierarchy, links.                                            | 1       |
| `get_us_statute_section_text` | Full HTML and plain text of a USC or CFR section.                                                                                    | 3       |

### Acts and legislation

| Tool                 | Description                                                                                                   | Credits |
| -------------------- | ------------------------------------------------------------------------------------------------------------- | ------- |
| `search_legislation` | Semantic search across acts, regulations, and state legislation. Filter by category, state, department, year. | 1       |
| `list_legislation`   | Browse acts to discover `act_id` values. Filter by category, state, department, status.                       | 1       |
| `get_act_text`       | URLs for full text, PDF, and HTML versions of an act.                                                         | 1       |
| `get_amendments`     | Complete amendment history for an act (substitutions, insertions, omissions).                                 | 1       |

## Authentication

The Vaquill MCP server authenticates with your Vaquill API key. Three options, in priority order:

1. **Bearer header** (remote): `Authorization: Bearer vq_key_...`
2. **Path token** (remote): `https://mcp.vaquill.ai/s/vq_key_...` - convenient when your client cannot send custom headers.
3. **Environment variable** (local): `VAQUILL_API_KEY=vq_key_...` for `uvx` / stdio launches.

Keys are scoped per workspace and revocable from the [dashboard](https://app.vaquill.ai/settings). For the full auth model, request signing, and rotation policy, see [Authentication](/docs/api-guide/authentication).

<Warning>
  Treat the path-token URL as a secret - anyone with the URL can spend credits from your account. Prefer the bearer-token form whenever the client supports it.
</Warning>

## Self-hosting

The MCP server is a thin wrapper around the public Vaquill API, so most users will not need to self-host. Run from source when you want to pin a version, add custom telemetry, or modify tool descriptions.

```bash theme={"theme":"github-dark"}
git clone https://github.com/Vaquill-AI/vaquill-mcp.git
cd vaquill-mcp
uv sync --all-extras

# Run locally over stdio
VAQUILL_API_KEY=vq_key_... uv run vaquill-mcp

# Inspect tools interactively
uv run fastmcp dev src/vaquill_mcp/server.py
```

The package fetches the OpenAPI spec from `https://api.vaquill.ai` at startup and auto-generates MCP tools with [FastMCP](https://github.com/jlowin/fastmcp). New API endpoints appear as tools automatically without a package upgrade.

## Environment variables

| Variable           | Required | Default                  | Description                                                                             |
| ------------------ | -------- | ------------------------ | --------------------------------------------------------------------------------------- |
| `VAQUILL_API_KEY`  | Yes      | -                        | Your API key (`vq_key_...`) from [vaquill.ai/settings](https://app.vaquill.ai/settings) |
| `VAQUILL_BASE_URL` | No       | `https://api.vaquill.ai` | API base URL. Override for staging or self-hosted API instances.                        |
| `VAQUILL_TIMEOUT`  | No       | `120`                    | Per-request timeout in seconds. Increase for large section-text fetches.                |

## Usage examples

Type these directly to Claude, Cursor, or any connected assistant.

**US law**

> *"What does 17 CFR 240.10b-5 say about insider trading?"*
>
> *"Find USC sections on equal protection under the Fourteenth Amendment."*
>
> *"What are the federal penalties for wire fraud under 18 USC 1343?"*
>
> *"Pull the full text of 26 USC 501(c)(3)."*

### Ready-to-run research prompt

<Prompt description="**Map a federal statute across USC and CFR.** Paste into any Vaquill-connected assistant. Replace the citation." icon="gavel" iconType="solid" actions={["copy"]}>
  Use the Vaquill MCP to map the statutory and regulatory framework for securities anti-fraud rules.

  Do these steps in order:

  1. Call `search_us_statutes` for "securities fraud" filtered to the USC to find the controlling sections.
  2. Call `get_us_statute_section_text` on the most relevant section to pull its full text.
  3. Repeat the search filtered to the CFR to find the implementing regulations (for example 17 CFR 240.10b-5).
  4. Produce a short outline: statutory hook, implementing regulation, and the key obligations each imposes.
  5. End with a one-sentence practitioner takeaway for a US compliance lead.

  Cite every factual claim back to the Vaquill tool that produced it. If a tool errors, show the error and continue with the next step.
</Prompt>

## Related

<CardGroup cols={2}>
  <Card title="MCP overview" icon="plug" href="/docs/integrations/mcp">
    All Vaquill MCP servers at a glance
  </Card>

  <Card title="Integrations" icon="grid" href="/docs/integrations">
    Chatbots, widgets, browser extensions, and automation
  </Card>

  <Card title="Authentication" icon="key" href="/docs/api-guide/authentication">
    API key setup and rotation
  </Card>

  <Card title="Search US statutes (API)" icon="magnifying-glass" href="/docs/api-reference/statutes/search-us-statutes">
    The underlying REST endpoint
  </Card>
</CardGroup>