MCP

Integrate Midpage's legal database with AI assistants using the Model Context Protocol. Research opinions, trial filings, dockets, statutes, and regulations through five tools.

Note: The v4 tools are in preview. Their names, fields, defaults, and behavior can still change at /mcp/v4 without a new major version. Refresh tools/list when connecting and check the changelog when updating an integration. MCP v3 remains available as a stable contract.

Versioning

These docs describe the current MCP contract, v4.

Midpage uses major versions for tool contract changes that integrations may need to account for, such as output schema changes or newly introduced tools. If your integration depends on fixed tool schemas or output fields, use a pinned version endpoint.

Previous version docs and migration notes:

• MCP v3: https://app.midpage.ai/mcp/v3
• MCP v2: https://app.midpage.ai/mcp/v2
• MCP v1: https://app.midpage.ai/mcp/v1
• MCP changelog

Base URL

https://app.midpage.ai/mcp/v4

Use this pinned URL for the v4 contract documented here. Older SSE clients can use /mcp/v4/sse with /mcp/v4/message.

If you want your integration to automatically receive the latest tool implementations, use the unversioned URL instead. It serves v4 today:

https://app.midpage.ai/mcp

Authentication

Midpage supports two authentication models for MCP integrations.

1. API Key

Use API key auth for non-interactive access, server-side jobs, or any integration that should run under one shared credential.

Generate an API key in the Developer Portal. If you need help, contact support@midpage.ai. Then send it in your MCP request headers as:

Authorization: Bearer <api_key>

2. OAuth

Use OAuth when your client should connect each user to their own Midpage account. Each user will need a Midpage account before they can sign in and authorize your client.

For most customers, the easiest setup is:

1. Point your client at https://app.midpage.ai/mcp/v4
2. Let your MCP or OAuth library follow Midpage's discovery metadata and register a client automatically if it supports dynamic client registration
3. Let the user sign in and approve access when prompted

Most MCP clients should not need pre-provisioned OAuth app credentials. Midpage's Clerk auth server supports dynamic client registration, so compatible clients can create their own credentials automatically. If your client cannot do that and needs a pre-provisioned OAuth app, contact Midpage.

GET https://clerk.midpage.ai/oauth/authorize?
  response_type=code&
  client_id=YOUR_CLIENT_ID&
  redirect_uri=https://your-app.com/oauth/callback&
  resource=https%3A%2F%2Fapp.midpage.ai&
  scope=profile%20email%20openid%20offline_access&
  state=RANDOM_VALUE&
  code_challenge=BASE64URL_SHA256(code_verifier)&
  code_challenge_method=S256

curl -X POST "https://clerk.midpage.ai/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=https://your-app.com/oauth/callback" \
  -d "resource=https://app.midpage.ai" \
  -d "code_verifier=YOUR_CODE_VERIFIER"

curl -X POST "https://clerk.midpage.ai/oauth/token" \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=https://your-app.com/oauth/callback" \
  -d "resource=https://app.midpage.ai"

Authorization: Bearer <access_token>

Testing in Hosted MCP Clients

If you just want to try Midpage in Claude, Codex, Perplexity, Cursor, or another hosted MCP client, add https://app.midpage.ai/mcp/v4 and sign in with your Midpage account when prompted.

You can create a free trial account at app.midpage.ai. For production integrations, use API key auth or OAuth as described above.

Choose a tool

For case research, search first and pass document.documentId to analyzeCaseDocument. For a known court and docket number, start with analyzeCaseDocket; pass a selected entry's documentReference plus your question to analyzeCaseDocument.

Search snippets and docket entry descriptions are discovery aids. Analyze the actual document before attributing arguments or holdings to it. analyzeCaseDocument lists the Negative and Caution citing opinions it finds under treatment.history. That is not a complete good-law check, and neutral treatment is not proof that an authority remains valid.

Use tools/list to discover the current schemas. Tool results are JSON serialized inside MCP content blocks of type text, rather than structuredContent. Check MCP isError before parsing: authentication, validation, and execution errors can be plain text. For JSON results, also inspect the tool's status or error; a partial search can contain usable results.

search

Send one to four phrasings of the same research question. The tool merges and deduplicates their results. Hits found by more queries rank first, then by their best rank within a query.

Input

The top-level field is queries, an array of one to four query objects. Each new query accepts:

Filters compose with AND. For example, a state filter and a named court must agree. Unknown fields are rejected. Optional unused filters may be omitted or null.

The complete documentTypes vocabulary is:

all, opinion, brief, motion, order, transcript, other, unknown,
judgment, memorandum, answer, complaint, declaration, stipulation,
exhibit, notice, summons, certificate, letter, report,
expert_report, settlement_agreement, procedural

Outside state trial courts, search covers opinion documents. Non-opinion types require a state trial search; all does not enable federal filing search. Use analyzeCaseDocket for federal filings. A filtered miss does not establish that no document exists: classifications and coverage can be incomplete. Retry an empty type-filtered query with ["all"]; retry an empty named-court trial query once statewide without courts, keeping the state and subject.

{
  "queries": [
    {
      "query": "PSLRA safe harbor statements of current fact",
      "courts": ["9th Cir."]
    },
    {
      "query": "forward looking statement mixed present historical facts",
      "courts": ["9th Cir."]
    }
  ]
}

A state trial filing search:

{
  "queries": [
    {
      "query": "SUNTRUST BANK SKIDMORE IRRIGATION",
      "jurisdiction": "trial",
      "states": ["Florida"],
      "documentTypes": ["motion", "order"]
    }
  ]
}

Output

Each hit has a case with caseId, caseName, court, and optionally docketNumber and url. A readable document has document.documentId, documentType, and url. Opinion metadata is under document.opinion: citation, dateDecided when known, publishStatus, and treatment (status, citationCount, negative, caution). Filing hits can also have entry with available entryNumber and dateFiled; hits without a document may include entryId. Opinion hits omit entry. snippet is optional and is not a verified quotation.

Use UUIDs from the returned fields. The numeric ID inside an opinion reader URL is not a documentId.

Continue with only the returned cursor:

{
  "queries": [{ "cursor": "COPY_NEXT_CURSOR_HERE" }]
}

Do not combine a cursor with a new query or filters. Cursors expire after 30 minutes. A search exposes at most 100 results across pages; when no cursor remains, refine the query if you need more. An exact federal docket lookup may instead return skipped[].nextAction directing you to analyzeCaseDocket.

analyzeCaseDocument

Read one opinion or filing against a legal question. The tool returns source-extracted quotations and an answer, rather than the full document text.

Input

Provide one usable reference. If several are supplied, precedence is documentId, then citation, then entry. Omit or set unused references to null. For a main filing, omit attachmentNumber or send null, "", or "0". For an attachment, send its positive integer number as a string, such as "1"; "14-1" is not an attachment number.

{
  "citation": "556 U.S. 662",
  "question": "Are threadbare recitals of a cause of action entitled to an assumption of truth?"
}

To read a docket attachment, copy the case and entry reference returned by docket analysis:

{
  "entry": {
    "caseId": "8e00e661-a0c3-5c29-9002-1e7eb0d5730d",
    "entryNumber": "14",
    "attachmentNumber": "1"
  },
  "question": "What facts does this exhibit establish?"
}

The attachment example illustrates the input shape, not a claim that this case has that attachment. Use a returned reference for actual retrieval. Stored filings are preferred; a missing copy may require metered PACER acquisition.

Output

An ok result includes:

Preserve the qualifications in each proposition and any concurrence/dissent or party attribution in opinionSection. A proposed order is not an entered ruling. quoteTruncated: true means the returned quotation was shortened. Use deeplinkUrl when present, otherwise document.url, and copy the URL exactly. Do not invent page pinpoints or infer them from PDF page positions.

document.opinion.treatment summarizes the opinion's later history across every stored copy of it:

Read the listed citing opinions before relying on a flagged case.

Other statuses are invalid_reference, not_found, ambiguous, text_not_available, pacer_fetch_failed, and analysis_failed. Read message; candidates can support a corrected lookup and url can support manual reading. An unread filing must not be represented as analyzed.

analyzeCaseDocket

Answer questions about the case's metadata and recorded activity, including judges, parties, case category, and procedural history. Use it to locate filings, then analyze their contents separately.

Input

Provide caseId or docket; caseId takes precedence. forceFetch may incur a PACER charge and is ignored with a warning when PACER cannot serve the case. V4 can read stored docket material without an upfront premium gate; live PACER acquisition is metered, and an explicit refresh requires premium access. A first acquisition can require PACER even when forceFetch is omitted.

{
  "docket": {
    "court": "N.D. Ill.",
    "docketNumber": "1:16-cv-11057"
  },
  "question": "What was filed or entered during the past month?",
  "forceFetch": true
}

Output

documentReference is either { "documentId": "..." } or { "entry": { "caseId": "...", "entryNumber": "...", "attachmentNumber": null } }. Attachments use their number instead of null. Pass the object unchanged to analyzeCaseDocument and add question. A reference indicates an available retrieval path, not a guarantee that fetching will succeed.

Use the two report links for different purposes:

Copy these URLs exactly. Do not construct raw-download paths from reader URLs or use a download URL for a “View docket” link.

A recent acquisition timestamp does not prove the underlying report is current. In particular, a newly acquired RECAP report can be stale. A failed refresh does not establish that no new filings exist. Use liveFetchSucceeded, coverage, the requested period, and warnings when describing current status.

Other statuses are invalid_reference, not_found, ambiguous, pacer_fetch_failed, and analysis_failed, each with a message. Ambiguous lookups can return candidates. An analysis failure can also return a top-level downloadUrl for manual reading.

searchLaws

Full-text search over statutes, regulations, constitutions, and agency guidance — US federal plus all 50 states and DC. Use it to FIND the governing provision, then call analyzeLaw with the result's id before citing it. Results are current law by default (see the Laws API guide for the currency derivation). Inputs are strict: unknown keys are rejected rather than silently ignored.

Parameters:

Returns:

Never cite from snippets — they are relevance context. Call analyzeLaw with the result id and quote from its verified passages.

Example:

{
  "query": "telehealth prescribing controlled substances",
  "collectionTypes": ["regulation"],
  "states": ["California", "Texas"]
}

analyzeLaw

Analyze a statute, regulation, constitutional provision, or agency guidance document against a specific legal question, returning verified verbatim passages — the document text is analyzed internally and raw text is never returned. Resolves to the CURRENT version by default (see the Laws API guide for how currency is derived); container nodes return their children for navigation; versioned provisions return the full version chain with dates.

Parameters (provide exactly one of the four lookup keys):

* Provide exactly one of citation, registerCitation, path, or id

Returns:

Example:

{
  "citation": "21 C.F.R. § 820.30",
  "question": "What design control requirements apply to medical device manufacturers?"
}

Migrate from v3

V3 docket tools keep their premium-access gate. V4 admits stored material without that upfront gate; actual PACER retrieval remains metered. V4 is not a drop-in replacement: update tool names, reference fields, response parsing, citation links, and pagination together. Keep integrations on their existing version until they are ready to follow preview changes.

Changelog

See the MCP changelog for version history and migration notes.