djangorestframework-mcp-server

# djangorestframework-mcp-server [](https://github.com/Artui/djangorestframework-mcp-server/actions/workflows/tests.yml) [](https://pypi.org/project/djangorestframework-mcp-server/) [](https://pypi.org/project/djangorestframework-mcp-server/) [](https://pypi.org/project/djangorestframework-mcp-server/) [](https://artui.github.io/djangorestframework-mcp-server/) [](https://github.com/Artui/djangorestframework-mcp-server/actions/workflows/tests.yml) [](https://github.com/astral-sh/ruff) [](LICENSE) Expose [`djangorestframework-services`](https://github.com/Artui/djangorestframework-services) services and selectors as a [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server, conforming to MCP **2026-07-28** and **2025-11-25** (Streamable HTTP). ## Idea Register `ServiceSpec` instances directly — no DRF router or viewset involvement. The unit of registration is the `ServiceSpec`, not a view. ```python from django.urls import path from rest_framework_services.types.selector_kind import SelectorKind from rest_framework_services.types.selector_spec import SelectorSpec from rest_framework_services.types.service_spec import ServiceSpec from rest_framework_mcp import MCPServer server = MCPServer(name="my-app") server.register_service_tool( name="invoices.create", spec=ServiceSpec( service=create_invoice, input_serializer=InvoiceInputSerializer, output_selector_spec=SelectorSpec( kind=SelectorKind.RETRIEVE, output_serializer=InvoiceOutputSerializer, ), ), ) server.register_resource( name="invoice", uri_template="invoices://{pk}", selector=SelectorSpec( kind=SelectorKind.RETRIEVE, selector=get_invoice, output_serializer=InvoiceOutputSerializer, ), ) urlpatterns = [path("mcp/", server.urls)] ``` A decorator form is also supported (`@server.service_tool(...)` / `@server.resource(...)`). See the [quickstart](docs/quickstart.md) for the full end-to-end recipe. - **Services** (mutations) → MCP **tools**. - **Selectors** (reads) → MCP **resources**. - A single `/mcp` endpoint speaks Streamable HTTP. The `/.well-known/oauth-protected-resource` endpoint comes mounted alongside. ## What ships - **Tools** — `tools/list`, `tools/call` for `register_service_tool` (mutations) and `register_selector_tool` (reads, with optional `FilterSet` + ordering + pagination). - **Resources** — `resources/list`, `resources/templates/list`, `resources/read` against `SelectorSpec`-backed callables; RFC 6570 templated URIs. - **Prompts** — `prompts/list`, `prompts/get` against render callables returning strings, `PromptMessage`s, or async coroutines. - **In-process transport surface** — call tools without an HTTP round-trip: `MCPServer.call_tool` / `acall_tool` and `list_tools` / `alist_tools` drive the same dispatch and permission checks as the wire path, for embedding in agent bridges, toolsets, or management commands. `unavailable_tools` / `aunavailable_tools` name each tool the listing leaves out with the reason, so a bridge can tell its model why one is missing. - **Tool annotations** — pass `annotations=` at registration (or rely on the read/mutation default) to advertise MCP hints like `readOnlyHint` / `destructiveHint` on `tools/list`. - **Generic `_meta`** — pass `meta=` at registration to populate the base protocol's free-form `_meta` object on a tool, resource, or prompt's listing entry (and on the `contents` of `resources/read`). Passed through verbatim, so protocol extensions have somewhere to live. - **Interactive views (MCP Apps)** — `register_ui_resource(...)` declares an HTML view with typed CSP / permission metadata; `ui=UIToolMeta(...)` on a tool links its result to that view, and a host renders it inline in the chat. The render payload is the `structuredContent` you already emit, and a view's own `tools/call`s inherit your auth, permissions and rate limits. An extension over base MCP, so no protocol bump. We declare; the host sandboxes and renders. - **Pluggable auth** — `DjangoOAuthToolkitBackend` (default) and `AllowAnyBackend` (dev only). Per-binding `MCPPermission` classes (`ScopeRequired`, `DjangoPermRequired`) plus your own. - **RFC 8707 audience binding** when `RESOURCE_URL` is configured; **RFC 9728 PRM** served from the configured backend. - **Per-binding rate limits** — `MCPRateLimit` Protocol with `FixedWindowRateLimit`, `SlidingWindowRateLimit`, and `TokenBucketRateLimit` implementations shipped. - **Output formats** — JSON (default) and TOON (token-oriented; optional extra with safe JSON fallback). - **Async POST/DELETE + GET-side SSE push** — sync `urls` for WSGI, `async_urls` for ASGI; `MCPServer.notify(session_id, payload)` pushes JSON-RPC frames on the session's SSE stream. Per-worker `InMemorySSEBroker` or cross-worker `RedisSSEBroker` (behind `[redis]`); `Last-Event-ID` resume via `InMemorySSEReplayBuffer` / `RedisSSEReplayBuffer`. - **OpenTelemetry instrumentation** — `mcp.tools.call`, `mcp.resources.read`, `mcp.prompts.get` spans (no-op without the `[otel]` extra installed). - **Origin allowlist + protocol-version validation + session lifecycle** per the transport rules of both revisions. `2026-07-28` and later declare version, identity and capabilities on every request and hold no session; `2025-11-25` and earlier negotiate once through `initialize`. Both are served concurrently on one endpoint, because a legacy client has no fall-forward mechanism. ## Install ```bash pip install djangorestframework-mcp-server # JSON only pip install "djangorestframework-mcp-server[toon]" # +TOON encoder pip install "djangorestframework-mcp-server[oauth]" # +django-oauth-toolkit backend pip install "djangorestframework-mcp-server[redis]" # +Redis SSE broker for multi-worker ASGI pip install "djangorestframework-mcp-server[otel]" # +OpenTelemetry instrumentation pip install "djangorestframework-mcp-server[filter]" # +django-filter for selector-tool FilterSets pip install "djangorestframework-mcp-server[spectacular]" # +drf-spectacular schema overrides pip install "djangorestframework-mcp-server[jwt]" # +SimpleJWTCookieAdapter (djangorestframework-simplejwt) pip install "djangorestframework-mcp-server[toon,oauth,redis,otel,filter,spectacular,jwt]" # everything ``` …or with `uv`: ```bash uv add djangorestframework-mcp-server # JSON only uv add "djangorestframework-mcp-server[toon]" # +TOON encoder uv add "djangorestframework-mcp-server[oauth]" # +django-oauth-toolkit backend uv add "djangorestframework-mcp-server[redis]" # +Redis SSE broker for multi-worker ASGI uv add "djangorestframework-mcp-server[otel]" # +OpenTelemetry instrumentation uv add "djangorestframework-mcp-server[filter]" # +django-filter for selector-tool FilterSets uv add "djangorestframework-mcp-server[spectacular]" # +drf-spectacular schema overrides uv add "djangorestframework-mcp-server[jwt]" # +SimpleJWTCookieAdapter (djangorestframework-simplejwt) uv add "djangorestframework-mcp-server[toon,oauth,redis,otel,filter,spectacular,jwt]" # everything ``` Optional extras degrade gracefully: TOON falls back to JSON with a runtime warning if `python-toon` is not installed, and the OAuth backend module imports cleanly without `oauth2_provider`, so a server used in process needs no DOT. Mounting one over HTTP refuses without it, while the URLConf is imported. ## Try it Install [mcp-inspector](https://github.com/modelcontextprotocol/inspector) and point it at your dev server: ```bash npx @modelcontextprotocol/inspector --url http://localhost:8000/mcp/ ``` Inspector lists tools, fills in arguments from the generated JSON Schema, and walks the OAuth auth flow against your configured Authorization Server. ## Documentation - [Quickstart](docs/quickstart.md) — copy-pasteable end-to-end. - [Concepts](docs/concepts.md) — tools vs resources, sessions, output formats. - [Authentication](docs/auth.md) — backends, permissions, audience binding, bring-your-own AS recipe. - [Recipes](docs/recipes/index.md) — focused cookbook entries. - [Reference](docs/reference/index.md) — autodocs for every public symbol. ## License MIT.