fastmcp-django

---
name: fastmcp-django
description: Use when adding, changing, deploying, testing, or debugging FastMCP MCP servers in existing Django apps, including ASGI mounting, stdio or sidecar servers, Django ORM access from MCP tools, auth and permissions, Streamable HTTP deployment, and MCP client tests.
license: MIT
---

# FastMCP with Django

Use FastMCP to expose small, typed Django application capabilities to agents.
Keep Django as the source of truth for auth, permissions, validation, models,
transactions, and business rules. Treat FastMCP as the protocol layer around
existing application services.

## Tool Choice

- Prefer the standalone `fastmcp` package (`from fastmcp import FastMCP`) for
  new Python MCP work in Django.
- Use the official MCP Python SDK (`from mcp.server.fastmcp import FastMCP`)
  when the project has already standardized on it, needs lower-level protocol
  control, or a host explicitly requires SDK behavior.
- Consider `django-mcp-server` only when the project needs a Django-native
  package that works inside WSGI or declaratively exposes models/DRF APIs. Audit
  generated tool contracts and permissions before exposing private data.
- If the app already has a deliberate public OpenAPI surface, generated or
  proxied tools can help for a first pass. For production agents, prefer
  hand-curated tools with purpose-built names, schemas, permissions, and bounded
  outputs.

FastMCP docs track the project's `main` branch, so re-check current docs when
relying on recently added features or version badges.

## Resource Routing

Load only the files needed for the current task:

| Need | Read |
| --- | --- |
| Step-by-step implementation in an existing Django app | `workflows/add-fastmcp-to-django.md` |
| Stdio, HTTP sidecar, ASGI mount, and path-prefix examples | `references/transports.md` |
| Tool contract design, ORM boundaries, async rules, resources, and prompts | `references/tool-design.md` |
| Auth, deployment, tests, local checks, and debugging symptoms | `references/auth-deployment-testing.md` |

## Implementation Workflow

1. Read existing Django entrypoints first: `manage.py`, settings, `asgi.py`,
   `wsgi.py`, URL routing, auth middleware, APIs, background jobs, and
   deployment files.
2. Choose the transport boundary:
   - Use stdio for local desktop/editor MCP servers that run beside the app.
   - Use a separate FastMCP HTTP sidecar when Django is WSGI-only or MCP should
     scale independently.
   - Mount FastMCP into the Django ASGI process when the app already runs under
     ASGI and sharing process/domain is intentional.
3. Put MCP server registration in a small module such as `apps/core/mcp.py` or
   `project/mcp.py`.
4. Keep tool bodies thin. Call existing services, selectors, forms,
   serializers, policy methods, or domain functions.
5. Add tests through `fastmcp.Client` before wiring the transport. Most behavior
   should be tested in memory without a running web server.

## Core Rules

- Make every exposed capability explicit. Avoid generic SQL, generic model
  browsing, arbitrary imports, file path access, or "admin" tools unless the
  project has a clear allowlist and authorization plan.
- Use typed parameters, Pydantic constraints, return type annotations,
  docstrings, and small JSON-serializable return values.
- Pass durable identifiers, not Django model instances, request objects, lazy
  querysets, open files, or huge payloads.
- Paginate and cap list/search tools. Return stable IDs and summaries, not full
  model dumps.
- Inject the current user/account from validated auth context or a trusted
  dependency. Never let the model provide privileged identity fields in
  production.
- Use synchronous `def` FastMCP tools for ordinary Django ORM work unless the
  project has a clear async design.
- For long-lived MCP processes, call `close_old_connections()` around ORM work
  or centralize connection cleanup in a thin helper.
- Add timeouts to slow or externally dependent tools. Enqueue long-running work
  instead of holding MCP requests open.

## Verification

- Inspect tool names, schemas, and descriptions with `fastmcp list` or
  `fastmcp inspect` when tool contracts matter.
- Test allowed and denied users for every permissioned tool.
- Test invalid inputs, missing objects, pagination caps, destructive action
  confirmation, database state changes, and `transaction.on_commit` side
  effects.
- Add one HTTP transport smoke test when ASGI mounting, auth headers, proxy
  behavior, or URL paths changed.

## References

- FastMCP docs: https://gofastmcp.com/getting-started/welcome
- FastMCP GitHub: https://github.com/PrefectHQ/fastmcp
- FastMCP HTTP deployment: https://gofastmcp.com/deployment/http
- FastMCP tests: https://gofastmcp.com/development/tests
- FastMCP tools: https://gofastmcp.com/servers/tools
- FastMCP authentication: https://gofastmcp.com/servers/auth/authentication
- FastMCP dependency injection: https://gofastmcp.com/servers/dependency-injection
- Django async support: https://docs.djangoproject.com/en/5.2/topics/async/
- Django ASGI deployment: https://docs.djangoproject.com/en/5.2/howto/deployment/asgi/