Django: Django-mcpz, for making MCP servers

Developer Simon Willison released django-mcpz, a Django package for building Model Context Protocol (MCP) servers, targeting the latest MCP specification version 2026-07-28. The package uses that version's stateless transport, which removes the initialization handshake, session ID, and streaming event stream, allowing an MCP server to run inside a single synchronous Django view on a standard WSGI deployment without Channels or separate ASGI infrastructure. django-mcpz also works with the 2025 MCP versions that offered a stateless mode, and requires an auth argument because MCP servers expose application internals to network callers.

Django: introducing django-mcpz, for making MCP servers I made another package Say hello to django-mcpz https://django-mcpz.readthedocs.io/en/latest/ , for building Model Context Protocol MCP servers in your Django project. The package tagline is easy peasy MCP servers in Django. MCP, the place to be? MCP https://modelcontextprotocol.io/ specifies a way for LLMs to interact with external data sources. MCP servers can expose a set of tools , which are essentially functions that an LLM can call on behalf of a user. So, for example, a user can ask “where’s my pizza at?” and the LLM can call one or more tools on your pizza shop server to navigate your data and return the answer. Users can ask questions in natural language, and LLMs can interpret messy data in your system to return a clean, hopefully-correct answer. MCP is date-versioned, and the latest version, 2026-07-28 https://modelcontextprotocol.io/specification/2026-07-28/changelog , made the protocol much simpler by making it stateless, like ye olde HTTP APIs. There’s no longer an initialization handshake, no session ID, and no streaming event stream. Each request is a plain HTTP POST with a JSON body that gets one JSON response, like any other HTTP API. This new version is way easier to deploy for a typical synchronous, WSGI Django project. The previous default transport required the server to hold open streaming responses server-sent events and track sessions, which would entail a separate ASGI deployment using Channels https://channels.readthedocs.io/en/stable/ . Now, you can make an MCP server within a single synchronous Django view and keep it inside your normal WSGI deployment, no extra infrastructure required. One of my clients wants to deploy an MCP server for their app, and so I took it upon myself to take advantage of this new MCP version and build a ground-up implementation, rather than use the existing ASGI-based packages. The goal was to make it “easy peasy” to build an MCP server in your Django project, and so I named it django-mcpz “pz” read in the American way is “pea-zee”, as in “easy peasy” or maybe I should stick to calling it “pea-zed”? . django-mcpz targets the latest MCP version, 2026-07-28, with its stateless-by-default transport, but it still works with last year’s 2025 versions too, which also had a stateless mode. Client support seems widespread, and anyway, this is an ecosystem that moves fast. The basics Here’s the example from the README, a server for a shop with one tool that counts orders: python from typing import Literal import msgspec from django mcpz.server import MCPServer from django mcpz.bearer tokens.auth import token auth from example.models import Order server = MCPServer name="shop", version="1.0.0", instructions="Query the shop’s order database.", auth=token auth, class CountOrdersParams msgspec.Struct : status: Literal "pending", "shipped", "cancelled" | None = None class CountOrdersResult msgspec.Struct : count: int @server.tool description="Count Order rows, optionally filtered by status.", read only=True, def count orders request, params: CountOrdersParams - CountOrdersResult: qs = Order.objects.all if params.status is not None: qs = qs.filter status=params.status return CountOrdersResult count=qs.count Some notes: - MCPServer represents one server and its registry of tools. It works a bit like Django’s admin.site : you create one, register things on it, and route it like a plain old view function. The instructions are natural-language guidance for the LLM on how to use the server. - The auth argument is required, since an MCP server exposes your application’s internals to network callers. More on that below. - server.tool registers a plain function as a tool. The function receives the HttpRequest first, then its parameters, and Django’s request/response cycle applies as usual, so it can use the ORM, request.user , and anything else a view can. - Parameters and results are declared as msgspec https://msgspec.dev/ Struct classes. django-mcpz generates the tool’s JSON Schemas from the type annotations, and validates each call’s arguments before the tool runs. Mistyped or unknown arguments are rejected with in-band errors that the calling LLM can read and correct from. msgspec also handles all the JSON serialization and deserialization, via my recently-released django-msgspec https://adamj.eu/tech/2026/08/07/introducing-django-msgspec/ , so it’s fast. - read only=True sets one of the specification’s tool annotations , hints for client user interfaces about what a tool does. For example, an UI might not prompt for confirmation before calling a read-only tool, but it will for a write tool. The server is its own view function, so you route it directly in your urls.py : python from django.urls import path from example.mcp import server urlpatterns = path "mcp", server , And that’s all Deploy as normal, and your MCP server is live at /mcp . My editor, Zed , has MCP support https://zed.dev/docs/ai/mcp . I hooked it up to a test project running the above server code and had this brief conversation with an LLM: User count the number of orders in my shop Assistant <thinking This "shop" order counting tool has nothing to do with the actual blog project, so it looks like an unrelated test scenario. I'll just go ahead and use the tool as requested. </thinking Tool Call: Run MCP tool count orders Status: Completed {"count":42} Assistant Your shop has 42 orders in total. The LLM detected the “shop” as unrelated to my blog and guessed it was just a test. Well played. Everything else talking MCP should “just work” too, including Claude Code and Codex. Authentication Every server needs an auth callable, which runs before the request body is touched. It receives the request and returns None to allow it, or an HttpResponse to reject it. There’s a public callable for servers protected some other way, or that are genuinely public, and you can write your own for, say, an authenticating reverse proxy. But the two common cases are covered by optional apps within django-mcpz. Developer tools, like Claude Code, Codex, and Cursor, accept a pasted credential in their configuration. For them, there’s the django mcpz.bearer tokens app, which provides per-client bearer tokens, each acting as a user, and revocable one at a time. Add it to INSTALLED APPS , run migrate , and pass its token auth callable to your server, as in the example above. Then create tokens with a management command, which prints the token value once: bash $ python manage.py mcpz bearer-tokens create "Claude Code" --user alice ... …or in the admin. Only a hash of each token is stored, like Django does for passwords, so a leaked database dump does not reveal usable credentials. Hosted assistants, like Claude.ai and ChatGPT, offer no way to enter a header when adding a server. They connect through OAuth : the user clicks “connect”, logs in to your site, approves access, and the assistant receives tokens to call your server with. For these assistants, there’s the django mcpz.oauth app, an authorization server built into your project, implementing the MCP authorization specification https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization and the OAuth standards it draws on. Add the app, include its URLs, and pass its oauth auth callable to your server: python from django.urls import include, path from example.mcp import server urlpatterns = path "mcp", server , path "oauth/", include "django mcpz.oauth.urls" , path "", include "django mcpz.oauth.wellknown" , The app reads everything it needs from your URLconf and each request, so there’s nothing else to configure. It ships with a consent page, rendered from templates you can override to match your site, and admin pages for managing clients and tokens. To serve both kinds of client from one server, combine the two callables in a few lines, as covered in the docs https://django-mcpz.readthedocs.io/en/latest/oauth.html serving-developer-tools-too . MCPizza The django-mcpz repository contains an example project https://github.com/adamchainz/django-mcpz/tree/main/example that serves a local MCP server for a pizza place called MCPizza not to be confused with McPizza https://mcdonalds.fandom.com/wiki/McPizza . It has tools to check today’s date, search the menu, place an order, chart today’s orders as an image, and link to the menu web page. The example is intended to show a use case that allows an LLM to make decisions based on freeform text in a database. Each pizza has structured fields the server enforces, such as price and the dates a special runs between, as well as freeform notes that an LLM can act on, such as “Vegan cheese available on request”. Here’s an example from the README, using Claude Code to query the server, calling the current date and search menu tools: bash $ claude --mcp-config mcp.json --strict-mcp-config --allowedTools "mcp mcpizza " \ -p "What vegetarian pizzas could I order tomorrow for under \$12? I'd prefer vegan if they can do it." For tomorrow 2026-09-04 , the vegetarian options under $12 are: - Null Pointer – $6 — plain base, vegan by default no cheese/toppings - Garlic Bread Technically a Pizza – $5.50 — vegetarian; GF base available, but not noted as vegan-adaptable - Margherita of Theseus – $9.50 — vegetarian, vegan cheese available on request - The Off-By-One mushrooms, olives, red onion – $10.50 — vegetarian, vegan cheese available on request Since you'd prefer vegan: Margherita of Theseus or The Off-By-One both work with vegan cheese swapped in, and Null Pointer is vegan as-is though it's just a plain base . Want me to place an order for one of these? The README also covers querying it with the llm https://llm.datasette.io/ CLI and the official MCP Python SDK. Give it a whirl and inspect the code to learn more Future workings django-mcpz implements MCP Tools callable functions , since that’s what most Django projects need. There are other parts of the protocol that it might gain, depending on demand: - Elicitations - server-generated questions for users to answer, that can guide your tool to the right data. - Prompts - text templates to guide LLMs in using your server for particular tasks. - Resources - API-like data access, for LLMs to query your server’s data directly, rather than through tools. There’s no plan at current for django-mcpz to implement streaming events or async support, since the goal for the package is a simpler implementation that fits the typical Django deployment. Check out my new book Boost Your GitHub DX https://adamchainz.gumroad.com/l/byghdx . One summary email a week, no spam, I pinky promise. Related posts: Tags: django https://adamj.eu/tech/tag/django/