OpenContracts exposes a read-mostly Model Context Protocol (MCP) server for AI assistants to access corpuses, documents, annotations, relationships, and discussion threads. Anonymous callers can read public resources; authenticated callers can also access private resources available to them and post messages in visible, unlocked threads.
Endpoints:
- Global (all public corpuses, anonymous):
POST /mcp/orGET /mcp/ - Authenticated (public + your private resources):
POST /mcp/me/orGET /mcp/me/ - Corpus-Scoped (single corpus):
POST /mcp/corpus/{corpus_slug}/orGET /mcp/corpus/{corpus_slug}/ - SSE (deprecated):
GET /sse/,POST /sse/messages/
Scope: /mcp/ and /mcp/corpus/... expose public resources to anonymous
callers; /mcp/me/ requires sign-in and additionally exposes private resources
the authenticated user owns or is shared on. A valid Authorization: Bearer <JWT> is honored on any endpoint.
Auth: Optional on /mcp/ (anonymous = public only). Required on /mcp/me/,
which returns 401 + WWW-Authenticate to unauthenticated callers so interactive
clients (Claude web/desktop, ChatGPT) start the OAuth 2.1 sign-in flow. See
Authentication below.
Global Access (all public corpuses):
Add to ~/.config/Claude/claude_desktop_config.json:
{
"mcpServers": {
"opencontracts": {
"command": "npx",
"args": [
"mcp-remote",
"https://your-instance.com/mcp/"
]
}
}
}Corpus-Scoped Access (single corpus - shareable link):
{
"mcpServers": {
"my-legal-corpus": {
"command": "npx",
"args": [
"mcp-remote",
"https://your-instance.com/mcp/corpus/my-corpus-slug/"
]
}
}
}Tip: Corpus-scoped links are ideal for sharing with collaborators. They provide focused access to a specific corpus without needing to know the corpus slug.
Both endpoints advertise the same tools. Authentication determines which
resources the caller can access; create_thread_message always requires an
authenticated session.
| Tool | Description |
|---|---|
list_public_corpuses |
List visible corpuses (public for anonymous callers; also accessible private corpuses for authenticated callers), paginated and searchable |
list_documents |
List documents in a corpus (requires corpus_slug) |
get_document_text |
Get a bounded slice of extracted text (char_offset, max_chars) |
list_annotations |
List annotations on a document (filter by page, label_text, text_contains, structural) |
list_relationships |
List labeled source-to-target relationships in a corpus, optionally filtered by document, label, or structural status |
search_corpus |
Search passages and/or blocks (granularity), with a text fallback for passages |
list_threads |
List discussion threads in a corpus |
get_thread_messages |
Get messages in a thread (flat or hierarchical) |
create_thread_message |
Post to a visible, unlocked thread; requires authentication, corpus_slug, thread_id, and content, with optional parent_message_id |
When using a corpus-scoped endpoint, tools are simplified - no corpus_slug parameter needed:
| Tool | Description |
|---|---|
get_corpus_info |
Get detailed info about the scoped corpus (replaces list_public_corpuses) |
list_documents |
List documents (no corpus_slug needed) |
get_document_text |
Get a bounded text slice (document_slug required; optional char_offset, max_chars) |
list_annotations |
List annotations (document_slug required; same filters as the global tool) |
list_relationships |
List corpus relationships; optional document, label, or structural filters |
search_corpus |
Search passages and/or blocks (query required; same search options as the global tool) |
list_threads |
List threads (no corpus_slug needed) |
get_thread_messages |
Get messages (only thread_id needed) |
create_thread_message |
Post to a visible, unlocked thread; requires authentication, thread_id, and content, with optional parent_message_id |
The authoritative input schemas are
server.py::get_tool_definitions and get_scoped_tool_definitions.
get_document_text returns text, total_chars, char_offset, next_offset,
and truncated. To continue reading, pass the returned next_offset as the
next request's char_offset; stop when next_offset is null. Use a positive
max_chars to make progress. Default and maximum slice sizes are defined in
constants/mcp.py.
The document:// resource still returns full extracted text.
search_corpus accepts granularity="passage", "block", or "both"
(default). Results are tagged with type. Passage search falls back to
case-insensitive substring matching on annotation text when vector search is
unavailable, fails, or returns no passages; those hits have a null
similarity_score. Block search requires embeddings and has no text fallback.
The optional structural filter applies to passages. See
tools.py::get_document_text and search_corpus
for retrieval behavior and
formatters.py for result shapes.
Resources use URI patterns for direct access:
| URI Pattern | Description |
|---|---|
corpus://{corpus_slug} |
Corpus metadata and document list |
document://{corpus_slug}/{document_slug} |
Document with extracted text |
annotation://{corpus_slug}/{document_slug}/{annotation_id} |
Specific annotation |
thread://{corpus_slug}/threads/{thread_id} |
Thread with messages |
The primary transport, introduced in MCP spec 2025-03-26. Stateless mode - each request is independent.
# Test with curl
curl -X POST https://your-instance.com/mcp/ \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'Scoped endpoints provide access to a single corpus. Perfect for sharing with collaborators:
# Get corpus info (no corpus_slug needed in arguments)
curl -X POST https://your-instance.com/mcp/corpus/my-corpus-slug/ \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc": "2.0", "method": "tools/call", "params": {"name": "get_corpus_info", "arguments": {}}, "id": 1}'
# Search within the scoped corpus
curl -X POST https://your-instance.com/mcp/corpus/my-corpus-slug/ \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc": "2.0", "method": "tools/call", "params": {"name": "search_corpus", "arguments": {"query": "indemnification clause"}}, "id": 2}'For older MCP clients that use the deprecated SSE transport (pre-2025-03-26 spec):
# SSE connection (GET) - establishes SSE stream
curl https://your-instance.com/sse/
# Messages endpoint (POST) - send messages to the server
curl -X POST https://your-instance.com/sse/messages/?session_id=<id> \
-H "Content-Type: application/json" \
-d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'For local development or direct integration:
cd /path/to/OpenContracts
python -m opencontractserver.mcp.server{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "list_public_corpuses",
"arguments": {"limit": 10}
},
"id": 1
}{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "search_corpus",
"arguments": {
"corpus_slug": "my-corpus",
"query": "indemnification clause",
"limit": 5
}
},
"id": 2
}{
"jsonrpc": "2.0",
"method": "resources/read",
"params": {
"uri": "document://my-corpus/contract-2024"
},
"id": 3
}HTTP requests are routed through ASGI to the global or corpus-scoped MCP server; SSE remains available for older clients, and stdio supports local use. Both servers advertise nine tools and four resource URI patterns. Handlers use the anonymous or authenticated user context for resource visibility checks.
| Aspect | Global (/mcp/) |
Corpus-Scoped (/mcp/corpus/{slug}/) |
|---|---|---|
| Use Case | Discover and explore all public corpuses | Share focused access to specific corpus |
| Tool Parameters | Requires corpus_slug for most tools |
corpus_slug auto-injected |
| Server Instance | Single global server | One server per corpus (cached) |
| Shareable | Yes, but requires knowing corpus slug | Yes, link contains the corpus |
Key files:
opencontractserver/mcp/server.py- Server setup, ASGI app, URI parsing, transport handlersopencontractserver/mcp/tools.py- Tool implementationsopencontractserver/mcp/resources.py- Resource handlersopencontractserver/mcp/formatters.py- Response formattersconfig/asgi.py- HTTP routing (/mcp/*and/sse/*→ MCP app)compose/production/traefik/traefik.yml- Production routing (Traefik)
Both servers are mcp.server.Server instances from the official
python-sdk 2.x
(requirements/base.txt pins mcp>=2.2.0,<3). Request handlers are passed as
on_*= constructor kwargs and return typed result models; the 1.x decorator
API no longer exists. The adapters in server.py (section MCP SDK HANDLER ADAPTERS: _build_on_call_tool, _build_on_list_tools,
_build_on_list_resource_templates, _on_read_resource) are the only code
that touches that SDK surface — create_mcp_server and
create_scoped_mcp_server compose them over the transport-agnostic
dispatchers (call_tool_handler, read_resource_handler, the scoped
call_tool closure), so a future SDK change is a one-place edit.
Contract preserved from 1.x and pinned by MCPSdkClientRoundTripTest
(opencontractserver/mcp/tests/test_mcp.py):
- Tool arguments are validated against the advertised
inputSchema; a mismatch returns anisErrorresult (Input validation error: ...) and still consumes the per-tool rate-limit bucket and records telemetry. - Exceptions escaping a dispatcher (unknown tool, rate limit) become
isErrorresults, never transport errors. DjangoPermissionDenied/ValidationError/DoesNotExistare structured{"error": ...}payloads. resources/readreturnsapplication/jsontext contents; a URI the caller cannot resolve (unknown pattern, invisible corpus) is a JSON-RPCINVALID_PARAMSerror carrying the message.
The server accepts an OAuth 2.1 / JWT Bearer token on the standard
Authorization header and validates it through the same pipeline as the rest of
the app (config/jwt_utils.py → Auth0 RS256/JWKS when USE_AUTH0=True,
otherwise the local graphql_jwt HS256 token).
/mcp/(and/mcp/corpus/...) — auth is optional. No token ⇒ anonymous (public resources only). A valid token ⇒ that user's private resources are also visible./mcp/me/— auth is required. An unauthenticated request gets401with aWWW-Authenticate: Bearer resource_metadata="…"header (RFC 6750 / RFC 9728). Interactive MCP clients follow that pointer to/.well-known/oauth-protected-resource[/mcp/me], discover the authorization server (Auth0), and run Authorization-Code + PKCE — no preconfigured token needed. Register/mcp/me/as the server URL in Claude web/desktop or ChatGPT to get the "Connect / Sign in" prompt.
| URL | Purpose |
|---|---|
/.well-known/mcp.json |
Lists the MCP servers (incl. cite-authenticated when Auth0 is on) |
/.well-known/oauth-protected-resource |
RFC 9728 metadata for the canonical /mcp resource |
/.well-known/oauth-protected-resource/mcp/me |
RFC 9728 path-based metadata for the authed resource |
For the interactive flow to complete end-to-end, the access token Auth0 issues must validate here:
- The Auth0 API Identifier (audience) must equal
AUTH0_API_AUDIENCE— the server validatesaudon every token. Map the advertised resource to that API so the RFC 8707resource/audiencethe client sends yields a JWT (not an opaque token). - Enable Dynamic Client Registration on the tenant — Claude/ChatGPT register themselves on the fly (RFC 7591).
- Set
MCP_PUBLIC_BASE_URL(e.g.https://contracts.opensource.legal) so the challenge advertises a trusted absolute URL rather than one derived from the requestHost(MCP bypassesALLOWED_HOSTS). - Browser clients / the MCP Inspector additionally need the calling origin in
MCP_CORS_ALLOWED_ORIGINS(defaults to Claude, ChatGPT, and the Inspector).
- Read-mostly: the only write tool (
create_thread_message) requires an authenticated caller with visibility of the corpus and thread. A separate WRITE permission is not required; locked threads reject posting. Optional parent messages must be visible and belong to the same thread. Seetools.py::create_thread_message. - Permission-filtered: anonymous callers resolve through
AnonymousUser; authenticated callers see only resources they own or are shared on - Identifiers: corpuses and documents use URL-safe slugs; annotations, relationships, threads, and messages also expose numeric identifiers. Knowing an identifier does not bypass the relevant visibility checks.
- Bearer auth: optional on
/mcp/, required on/mcp/me/(see above)
- No streaming of document text:
get_document_textuses bounded slices, while thedocument://resource returns full text - Semantic passage search and block search require embeddings; passage text fallback searches annotation text, not the entire extracted document
- Interactive OAuth sign-in requires
USE_AUTH0=True; without it,/mcp/me/still accepts a bearer token but cannot advertise an interactive login