Vaquill MCP Server - Vaquill AI

The Vaquill MCP server gives any Model Context Protocol client - Claude.ai, Claude Desktop, Claude Code, Cursor, VS Code, Windsurf - direct access to the Vaquill AI Developer API. It covers the full US corpus: the US Code, the CFR, every state and territory statutory code, state and federal regulations, court rules, constitutions, agency guidance and adjudications, session laws and the Federal Register. Source: github.com/Vaquill-AI/vaquill-mcp.

Two mounts, deliberately disjoint. https://mcp.vaquill.ai/s/_ serves the US corpus; https://mcp.vaquill.ai/in/s/_ serves Indian legislation. Each is built from its own OpenAPI document, so a US connection never exposes India tools and the reverse. The same vq_key_ works on both. Connect only the one you need: every connected server keeps its tool definitions in context for the whole conversation.

GitHub

Source code and issues

PyPI

uvx vaquill-mcp

Hosted endpoint

https://mcp.vaquill.ai

Quickstart

On Claude, the fastest path is now the connector: paste https://mcp.vaquill.ai/mcp, click Connect, and skip the key entirely. It is also the only path that works in Cowork. Everything below is the API-key setup, which is what Cursor, VS Code, Windsurf and other non-Claude clients need.

For a key-based setup, the fastest path is the hosted remote MCP on Claude.ai web - no install, no local Python, no config files.

Install Vaquill MCP in Claude Code with one paste. Replaces a manual config edit.

Get an API key

Generate a vq_key_... token from your dashboard settings. See Authentication.

Open Claude.ai Customize > Connectors

Click Add custom connector.

Paste the URL

Use either the path-token form:

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

Or keep the key out of the URL by opening Request headers in the same dialog and adding it 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_....

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.

Remote MCP connectors are 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. If you do not see it, use the path-token URL, or connect from Claude Code, Cursor, VS Code, or Windsurf, which all carry the header as written. On Team and Enterprise an owner adds the connector under Organization settings first.

Client setup

Pick your client below. The remote endpoint needs no install. The local uvx package reads the variables in Environment variables.

// Settings > Developer > Edit Config opens this file.
//   macOS    ~/Library/Application Support/Claude/claude_desktop_config.json
//   Windows  %APPDATA%\Claude\claude_desktop_config.json
//   Linux    ~/.config/Claude/claude_desktop_config.json
// Quit Claude completely and reopen it. It does not reload the file.
{
  "mcpServers": {
    "vaquill": {
      "command": "uvx",
      "args": ["vaquill-mcp"],
      "env": {
        "VAQUILL_API_KEY": "vq_key_your_key_here"
      }
    }
  }
}

# --scope user registers it for every project. The default is the current directory only.
claude mcp add --transport http --scope user vaquill \
  https://mcp.vaquill.ai/s/_ \
  --header "Authorization: Bearer vq_key_your_key_here"

# -e stores the key with the registration, so it survives Claude Code being launched from an IDE.
claude mcp add --scope user vaquill -e VAQUILL_API_KEY=vq_key_your_key_here \
  -- uvx vaquill-mcp

// ~/.cursor/mcp.json for every project, or .cursor/mcp.json for one.
{
  "mcpServers": {
    "vaquill": {
      "url": "https://mcp.vaquill.ai/s/_",
      "headers": {
        "Authorization": "Bearer vq_key_your_key_here"
      }
    }
  }
}

// ~/.cursor/mcp.json
{
  "mcpServers": {
    "vaquill": {
      "command": "uvx",
      "args": ["vaquill-mcp"],
      "env": {
        "VAQUILL_API_KEY": "vq_key_your_key_here"
      }
    }
  }
}

// .vscode/mcp.json. For every project, run the "MCP: Open User Configuration"
// command and use the same shape there.
{
  "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}"
      }
    }
  }
}

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

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

// ~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "vaquill": {
      "command": "uvx",
      "args": ["vaquill-mcp"],
      "env": {
        "VAQUILL_API_KEY": "vq_key_your_key_here"
      }
    }
  }
}

VS Code asks for the header value on first start and remembers it, which keeps the credential out of a file you commit. ${env:VAQUILL_API_KEY} works in Windsurf if you would rather read it from the environment. Both clients need the server restarted after you save the file before the tools appear.

The uvx runner requires Python 3.10+ and uv on PATH. uvx vaquill-mcp downloads and executes the package in an isolated env on first run; subsequent runs are instant.

Tools

Tools are generated from the OpenAPI document at startup, so the catalogue tracks the API rather than the package version. The US mount publishes 26 tools, one per API operation plus the search and fetch pair; the India mount publishes 22. Every tool is read-only: none creates, changes or deletes anything.

act_id is never assembled by hand. The title and section are derivable from a citation but the chapter is not, so a constructed id usually 404s and the failure reads like missing coverage. Take it from search_us_statutes, resolve_statute_citation or list_statute_divisions. See Section Identifiers.

Discovery

Tool	Description	Credits
`list_statutes_coverage`	The live coverage matrix: corpus legend, per-jurisdiction counts, freshness and retrieval status. Call this before treating an empty result as an absence.	Free
`get_pricing`	Current credit pricing per endpoint. No auth required.	Free
`list_statute_divisions`	Walk the statutory hierarchy one level down. Refunded on an empty level.	1

Search and retrieval

Tool	Description	Credits
`search_us_statutes`	Hybrid semantic and keyword search across every US corpus, with filters for `corpusType`, `state`, `code`, `source`, status, year and Federal Register facets.	4
`get_us_statute_section`	Section metadata by `act_id`: citation, hierarchy, breadcrumb, status and every format link.	2
`get_us_statute_section_text`	Full text. Supports `format=content` (operative text only, USC), `structured=true` for a subsection tree, and `asOf` for point-in-time.	6
`get_sections_batch`	Metadata for up to 50 `act_id`s in one call, with a diagnosis for each miss.	2 per section returned
`resolve_statute_citation`	Turn one citation string into the exact section, confirmed against the corpus.	2
`resolve_statute_citations_batch`	The same verdict for up to 50 citations at once.	2 per citation
`extract_statute_citations`	Paste a brief, memo or model answer and get every statute, regulation, court rule and constitution citation in it, each resolved. Case citations are not extracted. `resolve=false` lists them for free.	2 per distinct citation
`count_statute_sections`	How many sections a filter scope holds, before you page through it.	1

Section intelligence

Tool	Description	Credits
`get_section_changes`	Every observed add, amend and remove for one section, cursor-paged.	1
`get_section_neighbors`	The sections immediately before and after, in statutory order.	2
`get_section_cited_by`	Which USC and CFR sections cross-reference this one.	2
`get_section_definitions`	The defined terms from the chapter’s definitions section that govern this one.	4
`get_section_cross_state`	At most one comparable provision per other state, most similar first.	6

Each of these refunds a call it cannot answer, and returns a note explaining why. An empty result with a note is an explanation; without one it is a real answer.

State session laws

Tool	Description	Credits
`list_session_laws`	One state’s session laws (acts as enacted), filtered by session, approval date or effective date. `jurisdiction` is required. An empty page is charged.	1 per page
`get_session_law`	One law’s record: citation, session, dates, code sections affected, official sources and `textStatus`. Takes a `sessionLawId` or a citation (a citation adds the resolve price).	2
`get_session_law_body`	The law’s text exactly as printed, about 30,000 characters per page. Check `amendatoryMarkup`: if `lost`, struck language may read as law.	6 per page
`search_session_laws`	Find laws by what they say: plain words, a quoted phrase, a citation, a code section or a bill number. Keyword ranking, so a question has to share vocabulary with the act. Only enacted text is searched. An empty result is charged.	4 per page
`get_session_laws_batch`	Up to 50 laws by id or citation in one call; `includeBody` adds each law’s first page of text.	2 per law, plus 6 per page of text
`get_session_law_changes`	A cursor feed of every law served, corrected, withdrawn or merged.	1 per page
`get_section_enactments`	The session laws a publisher’s tables print against one code section, in CA, DC, HI, KY, MO, MS, NE, UT and WA.	1

Federal session laws are on the statute tools.

Account

Tool	Description	Credits
`get_credit_balance`	The credits your key can spend now, by source, the next expiry and your rate limits.	Free

Law change alerts are not MCP tools. Manage them in the console or over the REST API: see Law Change Alerts.

Generic aliases

Tool	Description	Credits
`search`	Single-string search, for clients that require this exact interface.	4
`fetch`	Single-string fetch by id, URL or citation, same constraint.	8, plus 2 for a citation

These exist for clients whose retrieval interface is matched by name and shape. Prefer the typed tools above: they take filters these two cannot express.

Resources and prompts

Beyond tools, the server publishes MCP resources and prompts. Clients that support them get the guidance without spending a tool call. Resources

URI	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. Read before a first substantive query.
`vaquill://us/coverage`	The live coverage matrix as a resource.
`vaquill://pricing`	Live per-endpoint credit pricing.
`vaquill://in/filters`	India mount: available act filters.

Prompts (US mount): good_law_check, fifty_state_survey, whats_changed, cite_check. Prompts (India mount): old_code_citation, indian_provision_check.

India mount

https://mcp.vaquill.ai/in/s/_ publishes the Indian legislation surface. It shares nothing with the US tools but the credential. The main tools:

Tool	Description	Credits
`search_acts`	Semantic search across Indian central and state enactments.	2
`list_acts`	Browse acts to discover identifiers.	1
`list_act_filters`	The filter vocabulary available for the two above.	Free
`get_act_text`	Full text of an act or provision.	3
`get_act_amendments`	Amendment history: substitutions, insertions, omissions.	5
`get_corresponding_provisions`	Map a provision in a repealed code to its successor.	1

Plus the search and fetch aliases.

Authentication

On the US endpoint https://mcp.vaquill.ai/mcp, the default is OAuth 2.1: the client opens a browser, you sign in with your Vaquill AI account and approve access, and there is no key to paste. It is the authorization code flow with PKCE (S256), discovered from /.well-known/oauth-protected-resource/mcp, with dynamic client registration and client ID metadata documents both supported. The access token lasts about an hour and is refreshed automatically. Clients that cannot run OAuth authenticate with your Vaquill API key instead. Three options, in priority order:

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

Keys are scoped per workspace and revocable from the dashboard. For the full auth model, request signing, and rotation policy, see Authentication.

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.

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.

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. 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
`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. Look up federal law

“What does 17 CFR 240.10b-5 say about insider trading?” “What are the federal penalties for wire fraud under 18 USC 1343?” “Pull the operative text of 26 USC 501(c)(3), without the amendment notes.”

Verify citations

“Check every statutory citation in this brief against the official text, and flag any that are no longer good law.” “Does Cal. Civ. Code 1950.5 resolve, and what is its current status?”

Compare across states

“How do other states word California’s security-deposit return deadline?” “Find the data-breach notification statute in New York, Texas and Illinois.”

Read law as it stood on a date

“What did 15 USC 1681c say on 2019-03-01, and how confident are we in that reconstruction?”

Find what changed

“What has changed in the CFR since last Tuesday?” “Which Texas acts take effect on September 1, 2025?”

Ready-to-run research prompt

Map a federal statute across USC and CFR. Paste into any Vaquill-connected assistant. Replace the citation.

MCP overview

All Vaquill MCP servers at a glance

Integrations

Chatbots, widgets, browser extensions, and automation

Authentication

API key setup and rotation

Search US statutes (API)

The underlying REST endpoint

GitHub

PyPI

Hosted endpoint

​Quickstart

​Client setup

​Tools

​Discovery

​Search and retrieval

​Section intelligence

​State session laws

​Account

​Generic aliases

​Resources and prompts

​India mount

​Authentication

​Self-hosting

​Environment variables

​Usage examples

​Ready-to-run research prompt

​Related

MCP overview

Integrations

Authentication

Search US statutes (API)

Quickstart

Client setup

Tools

Discovery

Search and retrieval

Section intelligence

State session laws

Account

Generic aliases

Resources and prompts

India mount

Authentication

Self-hosting

Environment variables

Usage examples

Ready-to-run research prompt

Related