MCP and HTTP surface¶

The server exposes two transport surfaces over the same runtime.

MCP (streamable HTTP)¶

Default transport: http://localhost:8001/mcp. Streamable HTTP per the MCP specification. Tools return JSON-compatible objects (not double-serialised JSON strings).

sequenceDiagram
  participant C as MCP Client
  participant S as legal-text-mcp-de
  participant D as Dataset

  C->>S: tools/call (get_norm, code=bgb, norm=242)
  S->>D: load (cached on first call)
  S->>S: resolve citation
  S-->>C: NormRecord JSON

Nine tools are exposed. See the MCP tools reference for the full list and parameters.

Starting the MCP server¶

DATASET_PATH=mcp/tests/fixtures/normalized \
STRICT_STARTUP=true \
PYTHONPATH=mcp \
uv run python mcp/server.py

Or with uvx (post-v1.0.0):

DATASET_PATH=/path/to/package uvx legal-text-mcp-de

Verifying MCP connectivity¶

curl http://localhost:8001/mcp -X POST \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Expected: JSON response listing nine tools.

HTTP API (FastAPI)¶

For non-MCP clients. Default port 8080. OpenAPI document at /openapi.json; Swagger UI available at /docs.

sequenceDiagram
  participant C as HTTP Client
  participant S as legal-text-mcp-de
  participant D as Dataset

  C->>S: GET /laws/bgb/norms/242
  S->>D: load (cached on first call)
  S-->>C: NormRecord JSON (HTTP 200)

Starting the HTTP API¶

DATASET_PATH=mcp/tests/fixtures/normalized \
STRICT_STARTUP=true \
PYTHONPATH=mcp \
uv run uvicorn http_api:app --host 127.0.0.1 --port 8080

HTTP endpoints¶

Shared runtime¶

Both surfaces share the same in-memory LegalTextRuntime instance. Dataset loading is lazy and cached — the first request loads the corpus, subsequent requests are fast. Consistency between MCP and HTTP responses is guaranteed by construction.

Related¶

• HTTP API overview
• Data modes