AGENT SKILL

fastmcp-django

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
最近更新
2026-11-14
Stars
★ 1.6k
Forks
491

01 前言 Front Matter

name
fastmcp-django
license
MIT
metadata
{ "tags": "fastmcp,django,mcp,asgi", "version": "0.1.0", "category": "Django", "displayName": "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.
compatibility
Codex, Claude Code, and other Agent Skills-compatible clients.

02 资源文件 6

03 SKILL.md 正文

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

04 同仓库更多 Skills

hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-review-with-annotations

Create, inspect, reply to, update, or resolve situated Worktable annotations. Use when feedback belongs to a Doc section, block, text range, or HTML Doc, or when the user asks to address existing review feedback and coordinate a requested artifact edit.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-find-and-synthesize-context

Find, assess, and synthesize context from Worktable Docs and Records. Use when the user asks what a workspace contains, wants workspace-backed research, needs current facts reconciled across artifacts, or requests a cited synthesis without changing workspace state.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-create-or-update-docs

Create, edit, rename, or maintain narrative Worktable Docs. Use for plans, decisions, briefs, notes, research syntheses, and other durable prose when the user requests a new artifact or a safe update to an existing one.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-create-or-manage-records

Organize repeated structured information as durable Worktable Records. Use for research datasets, inventories, directories, pipelines, trackers, and other collections whose items need identity, fields, filtering, links, validation, or individual updates.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-create-or-manage-interactive-html

Create or improve durable visual and interactive artifacts in Worktable. Use for dashboards, trackers, calculators, mini apps, slide presentations, and other requests that benefit from a polished HTML Doc.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-collaborate-threads

Read, answer, and hand off messages through durable Worktable threads with users or other authenticated participants. Use when the user asks to check addressed messages, reply to a participant, continue a thread, request another agent's help, wait briefly for a response, or watch for comments and messages sent to the agent.

★ 1.6k