djangorestframework-mcp-server

Expose djangorestframework-services services and selectors as a Model Context Protocol (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.

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 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, PromptMessages, 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/calls 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

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:

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 and point it at your dev server:

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 — copy-pasteable end-to-end.
Concepts — tools vs resources, sessions, output formats.
Authentication — backends, permissions, audience binding, bring-your-own AS recipe.
Recipes — focused cookbook entries.
Reference — autodocs for every public symbol.

License

MIT.

Metadata

Release files for djangorestframework-mcp-server 0.48.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for djangorestframework-mcp-server 0.48.0
File	Size	Uploaded
djangorestframework_mcp_server-0.48.0.tar.gz	954.3 kB	Sep 21, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for djangorestframework-mcp-server 0.48.0
File	Interpreter	ABI	Platform	Reset
djangorestframework_mcp_server-0.48.0-py3-none-any.whl 434.5 kB Sep 21, 2026	Python 3	none	any	Details

Total release size: 1.4 MB

Release files / djangorestframework_mcp_server-0.48.0.tar.gz

Download URL	djangorestframework_mcp_server-0.48.0.tar.gz
Size	954.3 kB
Tags	Source
SHA-256 checksum How to use checksums	`9c9f7976b70c1883d3779d3e13b8e9381a9784a2902f170808cd26d9b7435015`
BLAKE2b-256 checksum How to use checksums	`a54284d1d322e5657cc7e1773139c1c717b37b578b5b48ce8253101a8f7c6840`
Upload date	Sep 21, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/Artui/djangorestframework-mcp-server
Publishing commit: github.com/Artui/djangorestframework-mcp-server/tree/250b22b1126d53f1db8731083f85107b008d57bc

Workflow

Publishing configuration: github.com/Artui/djangorestframework-mcp-server/blob/250b22b1126d53f1db8731083f85107b008d57bc/.github/workflows/release.yml
Publishing logs: github.com/Artui/djangorestframework-mcp-server/actions/runs/35573620858/attempts/1

Artifact

Subject: djangorestframework_mcp_server-0.48.0.tar.gz
SHA-256 checksum: 9c9f7976b70c1883d3779d3e13b8e9381a9784a2902f170808cd26d9b7435015 Verifying attestations

Release files / djangorestframework_mcp_server-0.48.0-py3-none-any.whl

Download URL	djangorestframework_mcp_server-0.48.0-py3-none-any.whl
Size	434.5 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`ecefce9456b03b6eec040e30e3fff23ab59f31fd47d80b93ade2580035877920`
BLAKE2b-256 checksum How to use checksums	`d8216e549fe19b924da132e0fca43fc69721d74c072b23d4f6058a0f4fb2271e`
Upload date	Sep 21, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/Artui/djangorestframework-mcp-server
Publishing commit: github.com/Artui/djangorestframework-mcp-server/tree/250b22b1126d53f1db8731083f85107b008d57bc

Workflow

Publishing configuration: github.com/Artui/djangorestframework-mcp-server/blob/250b22b1126d53f1db8731083f85107b008d57bc/.github/workflows/release.yml
Publishing logs: github.com/Artui/djangorestframework-mcp-server/actions/runs/35573620858/attempts/1

Artifact

Subject: djangorestframework_mcp_server-0.48.0-py3-none-any.whl
SHA-256 checksum: ecefce9456b03b6eec040e30e3fff23ab59f31fd47d80b93ade2580035877920 Verifying attestations