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, listed on the MCP overview and in API coverage. Source: github.com/Vaquill-AI/vaquill-mcp.

This page covers the US mount, https://mcp.vaquill.ai/s/_. A separate mount exists for another corpus, described under India mount.

GitHub

Source code and issues

PyPI

uvx vaquill-mcp

Hosted endpoint

https://mcp.vaquill.ai

Quickstart

On Claude, the fastest path is 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 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. It needs no install, no local Python and 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 calls search_us_statutes and pulls 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 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 listed under Self-hosting.

// 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 follows the API, not the package version. There is one tool per API operation plus the search and fetch pair. Every tool is read-only: none creates, changes or deletes anything.

Never assemble an act_id by hand. The title and section can be derived from a citation but the chapter cannot, so a constructed id usually 404s and the failure looks like missing coverage. Take it from search_us_statutes, resolve_statute_citation or list_statute_divisions. See Section Identifiers.

Group	Tool	Description	Credits
Discovery	`list_statutes_coverage`	The live coverage matrix: corpus legend and per-jurisdiction counts.	Free
Discovery	`get_pricing`	Current credit pricing per endpoint. No auth required.	Free
Discovery	`get_credit_balance`	The credits your key can spend now, by source, the next expiry and your rate limits.	Free
Discovery	`list_statute_divisions`	Walk the statutory hierarchy one level down.	1
Search and retrieval	`search_us_statutes`	Hybrid semantic and keyword search across every US corpus.	4
Search and retrieval	`get_us_statute_section`	Section metadata by `act_id`.	2
Search and retrieval	`get_us_statute_section_text`	Full text of a section.	6
Search and retrieval	`get_sections_batch`	Metadata for up to 50 `act_id`s in one call.	2 per section returned
Search and retrieval	`resolve_statute_citation`	Turn one citation string into the exact section.	2
Search and retrieval	`resolve_statute_citations_batch`	The same verdict for up to 50 citations at once.	2 per citation
Search and retrieval	`extract_statute_citations`	Find and resolve every statute, regulation, court rule and constitution citation in pasted text.	2 per distinct citation
Search and retrieval	`count_statute_sections`	How many sections a filter scope holds, before you page through it.	1
Section intelligence	`get_section_changes`	Every observed add, amend and remove for one section, cursor-paged.	1
Section intelligence	`get_section_neighbors`	The sections immediately before and after, in statutory order.	2
Section intelligence	`get_section_cited_by`	Which USC and CFR sections cross-reference this one.	2
Section intelligence	`get_section_definitions`	The defined terms from the chapter’s definitions section that govern this one.	4
Section intelligence	`get_section_cross_state`	At most one comparable provision per other state, most similar first.	6
State session laws	`list_session_laws`	One state’s session laws (acts as enacted).	1 per page
State session laws	`get_session_law`	One law’s record.	2
State session laws	`get_session_law_body`	The law’s text as printed, about 30,000 characters per page.	6 per page
State session laws	`search_session_laws`	Find laws by what they say.	4 per page
State session laws	`get_session_laws_batch`	Up to 50 laws by id or citation in one call.	2 per law, plus 6 per page of text
State session laws	`get_session_law_changes`	A cursor feed of every law served, corrected, withdrawn or merged.	1 per page
State session laws	`get_section_enactments`	The session laws a publisher’s tables print against one code section.	1
Aliases	`search`	Single-string search, for clients that require this exact interface.	4
Aliases	`fetch`	Single-string fetch by id, URL or citation, same constraint.	8, plus 2 for a citation

Federal session laws are on the statute tools. Law change alerts are not MCP tools. Manage them in the console or over the REST API: see Law Change Alerts. Prefer the typed tools to the search and fetch aliases: they take filters these two cannot express. The aliases exist for clients whose retrieval interface is matched by name and shape, and ChatGPT and Codex explains when to use them.

Search and retrieval details

list_statutes_coverage: call it before treating an empty result as an absence.
search_us_statutes filters by corpusType, state, code, source, status, year and Federal Register facets.
get_us_statute_section returns citation, hierarchy, breadcrumb, status and every format link.
get_us_statute_section_text supports format=content (operative text only, USC), structured=true for a subsection tree, and asOf for point-in-time.
get_sections_batch adds a diagnosis for each miss.
resolve_statute_citation confirms the section against the corpus.
extract_statute_citations takes a pasted brief, memo or model answer and resolves each citation in it. Case citations are not extracted. resolve=false lists them for free.

Refunds and empty results

list_statute_divisions is refunded on an empty level.
Each section intelligence tool 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.
An empty page from list_session_laws is charged, and so is an empty result from search_session_laws.

Reading session-law bodies

list_session_laws filters by session, approval date or effective date, and jurisdiction is required.
get_session_law returns citation, session, dates, code sections affected, official sources and textStatus. It takes a sessionLawId or a citation, and a citation adds the resolve price.
get_session_law_body returns the text exactly as printed. Check textReliability and notice, and amendatoryMarkup: if lost, struck language may read as law.
search_session_laws accepts plain words, a quoted phrase, a citation, a code section or a bill number. It ranks by keyword, so a question has to share vocabulary with the act. Only enacted text is searched.
get_session_laws_batch with includeBody adds each law’s first page of text.
get_section_enactments covers CA, DC, HI, KY, MO, MS, NE, UT and WA.

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.

Prompts: good_law_check, fifty_state_survey, whats_changed, cite_check.

India mount

India is a separate mount with its own tools, resource and prompts. A US connection never exposes India tools, and an India connection never exposes US ones. Connect only the mount you need, because every connected server keeps its tool definitions in context for the whole conversation.

India mount: URL, tools, prompts and resource

https://mcp.vaquill.ai/in/s/_ publishes the Indian legislation surface. It shares nothing with the US tools but the credential: the same vq_key_ works on both mounts, and each is built from its own OpenAPI document. 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.Resource: vaquill://in/filters lists the available act filters.Prompts: old_code_citation, indian_provision_check.

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.

OAuth details

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_.... Use this 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, because anyone with the URL can spend credits from your account. Use 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 do not need to self-host.

Run from source

Run from source if you want to pin a version, add custom telemetry or change 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:

VAQUILL_API_KEY (required): your API key (vq_key_...) from app.vaquill.ai/settings.
VAQUILL_BASE_URL (optional, default https://api.vaquill.ai): API base URL. Override for staging or self-hosted API instances.
VAQUILL_TIMEOUT (optional, default 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

​Resources and prompts

​India mount

​Authentication

​Self-hosting

​Usage examples

​Ready-to-run research prompt

​Related

MCP overview

Integrations

Authentication

Search US statutes (API)

Quickstart

Client setup

Tools

Resources and prompts

India mount

Authentication

Self-hosting

Usage examples

Ready-to-run research prompt

Related