django-spec-mcp

Serve django-service-specs services and selectors as a Model Context Protocol (MCP) server, conforming to MCP 2026-07-28 and 2025-11-25 (Streamable HTTP).

Coming from djangorestframework-mcp-server (drf-mcp)? Read Moving from drf-mcp before the first deploy: the settings key, the stored names and the registration calls all change.

Idea

Register kernel specs directly. The unit of registration is a ServiceSpec or a SelectorSpec from django-service-specs, not a view: the spec says what an operation takes, who may run it and what it returns, and this package serves it over MCP. The same spec can be served by any other transport on the kernel.

from dataclasses import dataclass

from django.urls import path
from django_service_specs import (
    DataclassPresenter,
    DataclassValidator,
    Parameter,
    Parameters,
    SelectorKind,
    SelectorSpec,
    ServiceSpec,
    Unrestricted,
)

from django_spec_mcp import MCPServer


@dataclass
class InvoiceInput:
    number: str
    amount_cents: int


@dataclass
class InvoiceOutput:
    id: int
    number: str
    amount_cents: int


server = MCPServer(name="my-app", auth_backend=my_auth_backend)

server.register_tool(
    ServiceSpec(
        service=create_invoice,  # def create_invoice(*, number, amount_cents)
        validator=DataclassValidator(InvoiceInput),
        presenter=DataclassPresenter(InvoiceOutput),
        permissions=[Unrestricted()],
    ),
    name="invoices.create",
    description="Create an invoice.",
)

server.register_resource(
    SelectorSpec(
        kind=SelectorKind.RETRIEVE,
        selector=get_invoice,  # def get_invoice(*, pk)
        reads=Parameters([Parameter("pk", "integer", required=True)]),
        presenter=DataclassPresenter(InvoiceOutput),
        permissions=[Unrestricted()],
    ),
    name="invoice",
    uri_template="invoices://{pk}",
)

urlpatterns = [path("mcp/", server.urls)]

See the quickstart for the full end-to-end recipe.

• Services (mutations) and selectors (reads) → MCP tools, through register_tool; the spec's class says which kind of tool it is.
• A RETRIEVE selector → an MCP resource, through register_resource.
• A single /mcp endpoint speaks Streamable HTTP, with its protected-resource metadata mounted alongside. server.well_known_urls() also serves that document at RFC 9728's location, from the project's root URLconf.

This is the beginning of the README. Read the rest at the original. Read the full README ↗