OLDP MCP Server
The Open Legal Data Platform exposes a Model Context Protocol (MCP) server, enabling AI agents (Claude, Cursor, etc.) to search, retrieve, and navigate German legal data including court decisions and legislation with cross-references.
Quick Start
Claude Desktop / Claude Code
Add to your claude_desktop_config.json:
{
"mcpServers": {
"oldp": {
"url": "https://de.openlegaldata.io/mcp"
}
}
}
Claude.ai (Custom Connector)
Go to Settings → Connectors → Add Custom Connector
Enter URL:
https://de.openlegaldata.io/mcpClick Add — works immediately without login
Claude Code CLI
claude mcp add --transport http oldp https://de.openlegaldata.io/mcp
Authentication
The MCP server supports two modes:
Mode |
How it works |
Rate limit |
|---|---|---|
Anonymous |
No login required |
500 requests/hour (shared for Anthropic IPs) |
Authenticated |
OAuth 2.0 login with OLDP account (or API token) |
Same per-user budget as the REST API (5,000 requests/hour by default), shared across REST API and MCP |
Authenticated MCP requests and REST API requests draw from one per-user quota: every HTTP request to either surface counts against it, custom per-token limits and the profile-completion bonus apply to both, and the account dashboard shows the combined usage.
The whoami tool (and GET /api/whoami/ on the REST side) reports this from inside a conversation: whether the connection is signed in, the rate-limit tier, and how much of the budget is left. See Account.
OAuth Flow
The server implements OAuth 2.0 with PKCE and Dynamic Client Registration (RFC 7591). Discovery endpoints:
/.well-known/oauth-protected-resource— Resource metadata/.well-known/oauth-authorization-server— Authorization server metadata/oauth/register/— Dynamic Client Registration/oauth/authorize/— Authorization endpoint/oauth/token/— Token endpoint
The consent screen shown at /oauth/authorize/ overrides django-oauth-toolkit’s default template with oldp/assets/templates/oauth2_provider/authorize.html (OLDP micro layout, styles in scss/oldp/_oauth.scss). The template lives in the project template dir rather than the mcp app because oauth2_provider precedes oldp.apps.mcp in INSTALLED_APPS, so an app-level override would be shadowed.
Sign-in for write tools
The endpoint is open to anonymous callers. A tools/call of a tool that
needs an account (SIGN_IN_REQUIRED_TOOLS in oldp/apps/mcp/annotations.py,
currently only submit_feedback) without credentials is answered with HTTP
401 instead of a tool result:
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="api",resource_metadata="https://de.openlegaldata.io/.well-known/oauth-protected-resource/mcp"
{"message": "submit_feedback requires a signed-in connection. ...", "code": "not_authenticated"}
This is the MCP authorization challenge: a client whose connector signs in
only when the server asks (claude.ai: “Required when the server asks”) shows
its Connect prompt and retries after the OAuth flow. Every other 401 from
/mcp (invalid or expired token) carries the same resource_metadata
attribute, after any error="invalid_token" from django-oauth-toolkit.
ChatGPT offers its account linking for a tool error result rather than
an HTTP 401 (OpenAI auth guide).
ChatGPT tool calls carry _meta["openai/..."] fields (openai/subject,
openai/locale, …); an anonymous single tools/call of a sign-in-only
tool with such fields gets HTTP 200 and this result instead:
{"jsonrpc": "2.0", "id": 7, "result": {
"content": [{"type": "text", "text": "submit_feedback requires a signed-in connection. ..."}],
"isError": true,
"_meta": {"mcp/www_authenticate": [
"Bearer resource_metadata=\"https://de.openlegaldata.io/.well-known/oauth-protected-resource/mcp\", scope=\"read\", error=\"insufficient_scope\", error_description=\"submit_feedback requires signing in with an OLDP account\""
]}
}}
The openai/ fields only choose the format of the challenge and never grant
access; batches keep the HTTP 401. ChatGPT also needs each tool’s
securitySchemes (see Tool titles and annotations).
Available Tools
Discovery
Tool |
Description |
|---|---|
|
Platform coverage summary: total cases, laws, courts, date ranges (cached for |
|
Browse/filter courts by type, state, jurisdiction, level of appeal |
|
List available law books (BGB, StGB, GG, etc.) with section counts |
Search
Tool |
Description |
|---|---|
|
Unified search across BOTH laws and cases in one call, grouped by type ( |
|
Full-text search via Elasticsearch. Returns snippets, not full text. Accepts citation-graph filters ( |
|
Full-text search across law sections. Returns snippets only. |
|
Cases textually similar to a given case (Elasticsearch |
|
Structured ORM filtering by court, date, file number, ECLI, etc. |
See Search for the full filter matrix and combined-search examples across all three surfaces.
filter_cases returns the newest cases first with total and has_more.
Each of its database queries runs under a time limit
(DJANGO_MCP_DB_STATEMENT_TIMEOUT, default 3 seconds; MariaDB
max_statement_time, 0 disables it). Keep twice the value below the
gunicorn worker timeout, since one call runs up to two limited queries.
When a query runs out of time:
// The exact count took too long: the page is complete, total is a lower bound.
{"total": 21, "has_more": true, "total_is_lower_bound": true, "message": "…", "results": […]}
// The page itself took too long, e.g. a rare decision_type with no court or
// date filter (substring match, no index). Narrow the filters.
{"error": "This filter combination is too broad to answer in time.", "retryable": false, "hint": "…"}
Retrieval
Tool |
Description |
|---|---|
|
Full case by ID/slug: metadata plus complete (untruncated) plain-text |
|
Law text by book code + section (e.g. “BGB” + “823”), complete plain-text |
|
Detailed court info: name, address, contact, case count |
Text format
get_case and get_law_section return the document text as plain text,
not HTML (the REST API keeps serving the stored HTML). It is derived the
same way as the text in the search index — tags stripped, HTML entities
decoded (ä → ä), reference markers removed — and then normalized
so it is compact and readable:
line breaks and indentation in the HTML source count as spaces;
block elements (paragraphs, headings, list items, …) end a line and empty lines are dropped, so every paragraph is one line;
lists start on a new line and a list number or Randnummer stays on the line of its item (
1. Einkünfte aus …,12 Die Revision ist …);sentence numbers (
<sup>) are separated from the following word ((1) 1 Der Einkommensteuer unterliegen).
Markup-heavy decisions are therefore much shorter than their HTML (e.g. BGH VII ZR 105/18: 48,596 characters of HTML, 27,081 of text).
Reading long texts in snippets (offset / length)
The tools never truncate: with default arguments content holds the whole
text. Long decisions can exceed an agent’s context budget, so both tools
accept two optional integer parameters to read the text piece by piece:
Parameter |
Default |
Meaning |
|---|---|---|
|
|
Start position, in characters of the plain text described above |
|
|
Number of characters to return; |
Positions always refer to the plain text (identical to the full content),
never to the raw HTML.
As soon as offset or length is non-zero, the response omits content
and contains a snippet object next to the usual metadata:
{
"id": 318054,
"file_number": "VII ZR 105/18",
"...": "...",
"snippet": {
"text": "Tenor\nAuf die Revision des Beklagten ...",
"offset": 0,
"length": 10000,
"total_length": 27081,
"has_more": true,
"next_offset": 10000
}
}
Field |
Meaning |
|---|---|
|
The requested plain-text slice |
|
Start position of |
|
Actual length of |
|
Length of the whole plain text — use it to plan how many calls are needed |
|
|
|
Pass as |
To read a whole decision in chunks:
get_case(case_id=318054, length=10000)get_case(case_id=318054, offset=10000, length=10000)(the returnednext_offset)… repeat until
has_moreisfalse.
Negative values, or an offset greater than total_length, return an
{"error": ..., ...} payload (the latter includes total_length).
Deprecated: full_text and content_truncated
Earlier versions of get_case truncated content at 30,000 characters
unless full_text=True was passed (then at 100,000). Truncation has been
removed. For backwards compatibility:
full_textis still accepted (trueorfalse) but ignored; the content is always complete. Passing it adds adeprecation_warningslist to the response (and logs a server-side warning) telling the client to drop the argument and useoffset/lengthfor snippets.content_truncatedis still returned alongsidecontentand is alwaysfalse.
Note that in the same release content switched from HTML to plain text;
clients that need the HTML can use the REST API (/api/cases/<id>/,
/api/laws/<id>/).
Both will be removed in a future release; clients should stop sending
full_text and stop reading content_truncated.
Cross-References
Tool |
Description |
Backend |
|---|---|---|
|
Check if Aktenzeichen, ECLI, or § reference exists in the database |
SQL |
|
Forward refs: which laws and cases does a decision cite? A law reference extracted before the latest revision of its book was imported is shown as the same section of the latest revision (when it still exists there) |
SQL |
|
Reverse refs: which cases cite a given decision? |
Elasticsearch |
|
All cases interpreting a specific statute section; `sort=date |
most_cited` (landmark first) |
The same data is queryable via the
REST API’s citation surfaces:
nested actions like /api/cases/<id>/references/ for case-by-case
lookups, plus a flat /api/references/ resource with slug-based
filters (cited_by_law__book__slug=bgb&cited_by_law__slug=823) for
cross-cutting graph queries the MCP tools can’t express. The REST
nested actions and the MCP tools share a single service layer and
the same backends — references / forward-refs paths via the ORM,
citing_cases paths via Elasticsearch — so payload shapes match.
When Elasticsearch is unavailable, get_citing_cases and
get_cases_for_law return a structured error envelope rather than
silently degrading:
// Transient timeout — same query is sub-100ms after segments are
// paged in. Agent should wait + retry.
{"error": "Search timed out…", "retryable": true, "hint": "…"}
// Hard outage — retrying immediately won't help.
{"error": "Citation graph is temporarily unavailable. Try again in a few minutes.", "retryable": false}
Agents should branch on retryable rather than parsing the message.
See docs/elasticsearch.md
for the underlying CaseIndex.cited_laws / CaseIndex.cited_cases
fields.
Statistics
Tool |
Description |
|---|---|
|
Aggregated counts by court, year, jurisdiction. Without |
Account
Tool |
Description |
|---|---|
|
Who the connection is signed in as (or anonymous), how it authenticated, the rate-limit tier and the remaining budget, plus how to get a larger one |
Example response for an anonymous Claude connector user:
{
"authenticated": false,
"user": null,
"auth_method": null,
"rate_limit": {
"tier": "anonymous",
"bucket": "shared",
"limit": 500,
"window_seconds": 3600,
"used": 212,
"remaining": 288,
"retry_after_seconds": null
},
"upgrade": {
"action": "sign_up",
"url": "https://de.openlegaldata.io/accounts/signup/",
"limit": "5000 requests/hour",
"message": "You are not signed in. Anonymous requests from this client share one budget with all other anonymous users of the same connector. Create a free account and connect with OAuth (MCP) or send an API token (REST API) to get your own budget of 5000 requests/hour."
}
}
tier:anonymous,registered(default signed-in budget),enriched(profile-completion bonus) orcustom(per-token limit set by an admin).bucket:sharedwhen all anonymous users of the connector share one budget (requests from Anthropic’s IP range),ipfor other anonymous clients,userfor signed-in users (shared between MCP and the REST API).used/remainingcount HTTP requests in the sliding window, including thewhoamicall itself.retry_after_secondsis set only when nothing is left.upgradesuggestssign_upto anonymous callers andcomplete_profileto signed-in users without the bonus; it isnullotherwise.
The budget is read from the throttles’ own cache buckets, so it matches what the next request will be judged against. GET /api/whoami/ returns the same shape for the REST API’s budget (see API overview).
Feedback
Tool |
Description |
|---|---|
|
Send a feature request, bug report or data issue to the OLDP team. Signed-in users only (OAuth or API token); anonymous calls get HTTP 401 with an OAuth challenge (see Sign-in for write tools) |
The agent-facing counterpart of the contact form: the input is
emailed to SITE_EMAIL via Django’s email backend, with the account’s email
address as Reply-To, so the team can answer. Arguments:
category:feature_request,bug_report,data_issueorothermessage: the feedback, 20–5000 characterssubject(optional): one-line summary, max 200 characters; defaults to the first line of the messagecontext(optional): technical context such as tool calls, case IDs or law references, max 2000 characters
The email also names the user, how they authenticated and, for OAuth, the
connector (OAuth application name). Each user can submit at most
DJANGO_MCP_FEEDBACK_DAILY_LIMIT (default 10) messages per day; failed
deliveries return retryable: true and don’t count. The tool docstring asks
agents to submit only with the user’s consent and without personal data.
Tool titles and annotations
Every tool carries a human-readable title and MCP
tool annotations,
which clients use for display and to decide whether a call needs user
confirmation. All OLDP tools except submit_feedback only read OLDP’s own
data:
Annotation |
Read-only tools |
|
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
django-mcp-server registers toolset methods without titles or annotations,
so oldp/apps/mcp/annotations.py sets them on startup
(MCPConfig.ready()). When adding a tool, add its title to TOOL_TITLES
in that module (and its hints to TOOL_HINTS unless it is read-only); oldp/apps/mcp/tests/test_annotations.py fails for any
registered tool without one.
The same module sets _meta["securitySchemes"]
(OpenAI Apps SDK), which
tells ChatGPT whether a tool can be called anonymously:
Tools |
|
Meaning |
|---|---|---|
All except |
|
Works anonymously; signing in raises the rate limit |
|
|
Sign-in required |
Usage Examples
Legal Research
“Find BGH decisions from 2023 about § 823 BGB”
search_cases(query="§ 823 BGB", court_code="BGH", start_date="2023-01-01", end_date="2023-12-31")get_case(case_id=12345)for full text (orget_case(case_id=12345, length=10000)to read it in plain-text chunks)get_case_references(case_id=12345)for cited laws/cases
Citation Verification
“Is ‘VI ZR 123/22’ a valid BGH file number?”
validate_citation(citation="VI ZR 123/22")
Legislative Impact Analysis
“How is § 1004 BGB interpreted in case law?”
get_cases_for_law(book_code="BGB", section="1004")get_case(case_id=...)for relevant decisions
Design Principles
Verbatim text only: No AI-generated summaries. The agent summarizes; we provide the source.
Search → Retrieve pattern: Search returns snippets;
get_case/get_law_sectionreturns full text.Citation validation: Built-in hallucination guard for legal citations.
No truncation: Retrieval tools return the complete text. Agents that need to protect their context window request plain-text snippets via
offset/lengthinstead of relying on a server-side cut-off.
Directory Listings
Official MCP Registry
Each country deployment (de, later at, ch) is listed as its own server in
the official MCP Registry, which
many other directories (Glama, mcp.directory, PulseMCP, …) import from.
Instead of a checked-in server.json, the registry document is generated
from the deployment’s settings by a management command:
|
Source |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The three MCP_REGISTRY_* settings are empty in core and set by the country
theme (e.g. oldp_de.settings); they can also be given as
DJANGO_MCP_REGISTRY_* env vars. The command refuses to run while they are
empty, invalid or longer than the registry allows, and requires an https://
site URL. It needs no database or search backend.
Publishing uses the
mcp-publisher CLI.
One-time setup — generate a key pair (OpenSSL 3+) and print the public record:
openssl genpkey -algorithm Ed25519 -out mcp-registry-key.pem
echo "v=MCPv1; k=ed25519; p=$(openssl pkey -in mcp-registry-key.pem -pubout -outform DER | tail -c 32 | base64)"
Add the printed line as a DNS TXT record on the apex domain
openlegaldata.io. This proves control of io.openlegaldata/* (and all
subdomains), so it covers every country listing. Then, after each release:
export DJANGO_SETTINGS_MODULE=oldp_de.settings DJANGO_CONFIGURATION=ProdDEConfiguration
./manage.py mcp_server_json --output server.json
mcp-publisher login dns --domain openlegaldata.io \
--private-key "$(openssl pkey -in mcp-registry-key.pem -noout -text | grep -A3 'priv:' | tail -n +2 | tr -d ' :\n')"
mcp-publisher publish server.json
The registry accepts each version only once, so changed metadata is published with a new OLDP release. Registry names cannot be renamed after the first publish.
Alternatively, an instance can serve the HTTP proof itself: set
DJANGO_MCP_REGISTRY_AUTH to the printed v=MCPv1; ... line, which is then
served at /.well-known/mcp-registry-auth (404 while unset), and log in with
mcp-publisher login http --domain de.openlegaldata.io --private-key ....
HTTP verification only covers that exact host, so the name must then be
io.openlegaldata.de/<server>.
Claude connector directory
Submissions go through the directory portal in the claude.ai admin settings (see Anthropic’s submission guide). The review requires tool titles and annotations (see above), OAuth for authenticated access, and a privacy policy: https://de.openlegaldata.io/pages/privacy/.
ChatGPT plugin directory
OpenAI lists MCP servers as ChatGPT plugins. A plugin is submitted as a ZIP
package (plugin.json with listing and review metadata, mcp.json with the
server URL, icons) in the plugin portal at https://platform.openai.com/plugins;
see OpenAI’s submission guide.
The server side needs:
Domain verification. When connecting the server, the portal shows a token that must be served as plain text at
/.well-known/openai-apps-challenge. SetDJANGO_MCP_OPENAI_APPS_CHALLENGEto it (404 while unset).Authentication “mixed unauthenticated/OAuth”. Anonymous access with optional sign-in, declared per tool via
securitySchemes; anonymous calls of sign-in-only tools get the challenge described in Sign-in for write tools.OAuth. ChatGPT registers itself through Dynamic Client Registration (the server offers no CIMD) and, as the server does not advertise RFC 9207 issuer identification, uses a per-connection redirect URI
https://chatgpt.com/connector/oauth/{callback_id}; DCR accepts any HTTPS redirect URI, so nothing needs to be allowlisted.Tool annotations.
readOnlyHint,destructiveHintandopenWorldHintset explicitly on every tool (see above).
After publication OpenAI rescans the server daily: changed tool metadata goes live after automated checks, new tools need approval, and the server URL cannot change.
Disclaimer
This data is provided for informational purposes only and is not a substitute for professional legal advice. References are automatically extracted and may be incomplete. Verify critical citations against the full text.
Technical Details
Transport: Streamable HTTP at
/mcpPackage:
django-mcp-serverv0.5.7OAuth:
django-oauth-toolkitv3.xSearch: Elasticsearch 7.17 via django-haystack
Rejected requests: every 4xx answer from
/mcpis logged byoldp.mcp.transportasmcp_request_rejectedwith the status, the JSON-RPC method (never the arguments),MCP-Protocol-Version,Content-Type,Accept, body size, user agent and the reason from the response body. Requests fail there before any tool runs: a body that is not JSON (DRF, while OAuth2 authentication reads the form data), a body that is not one JSON-RPC message or an unsupported protocol version (MCP SDK), bad credentials or throttling. The access log only has the status code.