django-admin-fastmcp

A reusable Django app that exposes the Django admin as an MCP server, built on FastMCP.

Every tool call runs as the staff user who owns the bearer token. Every tool call asks the ModelAdmin for permission first. A superuser can do everything a superuser can do in the admin. A staff user can do exactly what that staff user can do in the admin, and nothing more.

SPEC.md is the full specification.

How it works

Three rules define the package:

1. No parallel permission system. Authorization delegates to the ModelAdmin methods: has_view_permission, has_add_permission, has_change_permission, has_delete_permission, get_queryset, get_readonly_fields, and get_actions. A get_queryset override that hides rows hides them from MCP too.

2. No parallel data surface. Writes go through the admin's own ModelForm and save_model, then record a LogEntry. The admin history page stays truthful.

3. Fail closed. Every unresolved lookup, missing ModelAdmin, unknown action, unknown field, and unknown tool denies the call.

Related MCP server: Globalping

Installation

uv add django-admin-fastmcp

Add the app to your settings:

INSTALLED_APPS = [
    ...,
    "django.contrib.admin",
    "django_admin_fastmcp",
]

ADMIN_FASTMCP = {
    "SERVER_NAME": "acme-admin",
    "EXCLUDE_MODELS": ("auth.Permission", "auth.Group"),
    "WRITABLE_MODELS": (),          # empty means no writes at all
}

Mount the OAuth endpoints on the same site as the admin:

# urls.py
urlpatterns = [
    # RFC 8414 fixes this one at the site root.
    path("", include("django_admin_fastmcp.well_known_urls")),
    # This prefix is yours to choose. Match it to the path in MCP_URL.
    path("admin/mcp/", include("django_admin_fastmcp.urls")),
    path("admin/", admin.site.urls),
]

The package hardcodes no prefix. Every URL the metadata document advertises comes from reverse(), so a project that mounts the endpoints at /backoffice/oauth/ gets that in discovery and clients follow it. Two rules: the well-known document belongs at the root, because a client derives its URL from the issuer, and the endpoints should sit on the same site as the admin, because the consent page rides the admin session cookie.

Apply the migrations:

python manage.py migrate django_admin_fastmcp

Nothing else. No per-model registration, no mixin, no decorators. The server exposes whatever the admin already exposes.

Connect a client

Run the server (see Deployment), then register it:

# Claude Code
claude mcp add --transport http acme-admin https://<host>/admin/mcp

Use the path with no trailing slash. /admin/mcp/ answers a 307 redirect to /admin/mcp, and not every client follows a redirect on POST.

No token, no header. The first call starts the standard MCP OAuth flow:

1. The client opens your browser at the authorize page on the Django site.

2. Your admin session cookie identifies you. If you are logged out, the normal admin login appears first.

3. A consent page shows the client name and what approval means. You approve.

4. The client receives its tokens and connects. It refreshes them by itself.

Any MCP client that speaks streamable HTTP with OAuth works the same way, for example Cursor or a FastMCP Client.

Rules around access:

• Any staff user can authorize a client, for themselves only.

• A grant acts with your own admin permissions, never more. There is no separate permission system: whoever may change a model in the admin may change it over MCP, when the server lists that model in WRITABLE_MODELS.

• Refresh tokens expire after REFRESH_TOKEN_TTL_DAYS (default 90), so re-consent happens that often. Revocation is an admin action on the grant changelist.

Tools

Eleven generic tools, mounted under the namespace admin, so wire names are admin_list_models and so on. Each takes model as "app_label.ModelName". The tool list is static. What varies per user is what each tool lets that user see and do.

Read

Write

Write tools need the model listed in WRITABLE_MODELS; your own admin permissions decide the rest, per model and per object. A model outside the list refuses every write and every action, whoever calls. Leave sensitive models out, an event log for example, and no MCP client can ever write to them.

Every returned row carries pk as a string and an admin_url, so an agent can hand a person a link into the real admin.

Settings

All keys live in the ADMIN_FASTMCP dict. An unknown key is an error at startup.

Set SITE_URL and MCP_URL for any real deployment. MCP_URL is the single source of three things that must agree: the path the endpoint is served on, the resource that discovery advertises, and the audience every token is bound to. Its path defaults to /admin/mcp. A startup check refuses a MCP_URL with no path, because then the whole origin would be advertised as the protected resource.

Per-ModelAdmin knobs

Set these on a ModelAdmin class, no mixin needed:

class InvoiceAdmin(admin.ModelAdmin):
    mcp_expose = False                     # hide this model from MCP entirely
    mcp_fields = ("number", "total")       # allowlist of serialized fields
    mcp_exclude_fields = ("internal_note",)  # denylist of serialized fields

REDACT_FIELDS wins over mcp_fields. Listing a password field explicitly does not reveal it.

Safety

An admin MCP server for a superuser is a remote shell over the production database, driven by a language model. The rails:

• WRITABLE_MODELS defaults to empty, so no model accepts writes until the deployment names it. Everything else is your ordinary Django permissions, asked through the ModelAdmin on every call.

• Access tokens are short-lived. Only salted hashes are stored, so a leaked database row cannot be replayed.

• delete_object and run_action preview by default and change nothing until confirm=True.

• Every mutation records a LogEntry attributed to the grant's user, with the client name in the change message, for example "Changed status. Via MCP (client: Claude Code).". A write that cannot record a LogEntry rolls back.

• The package's own models, sessions.Session, and authtoken.Token are never exposed, whatever the settings say.

• Keep auth.Permission and auth.Group out of WRITABLE_MODELS. An agent that can grant permissions can escape the permission model.

Observability

The package instruments every tool call: a Sentry span or transaction named after the tool (admin_search_objects), tagged with the model, the Django user, the OAuth client, and the outcome (ok, denied, error); a counter and a duration distribution per tool; and one structured log record per call on the django_admin_fastmcp logger (denials at WARNING). Unexpected exceptions are captured with full context. Logfire is supported the same way.

Both backends are optional. Nothing here runs unless the library is installed and initialized:

uv add "django-admin-fastmcp[sentry]"     # or [logfire], or both

Setting up Sentry

Initialize the SDK in settings.py, gated on the DSN, the same way a normal Django deployment does:

SENTRY_DSN = env.get("SENTRY_DSN")

if SENTRY_DSN:
    import sentry_sdk
    from sentry_sdk.integrations.django import DjangoIntegration
    from sentry_sdk.integrations.logging import LoggingIntegration

    sentry_sdk.init(
        dsn=SENTRY_DSN,
        environment=env.get("SENTRY_ENVIRONMENT", "production"),
        integrations=[DjangoIntegration(), LoggingIntegration()],
        traces_sample_rate=float(env.get("SENTRY_TRACES_SAMPLE_RATE", "0.5")),
        # The spans tag the calling username. Keep this on if you want it.
        send_default_pii=True,
        enable_logs=True,
    )

ADMIN_FASTMCP = {
    ...,
    "ENABLE_SENTRY_TRACING": bool(SENTRY_DSN),
}

That single init covers both processes. The web process reports the OAuth views through DjangoIntegration as usual. The admin_mcp_serve process loads the same settings, so the SDK is active there too; the package opens its own transaction per tool call, so tool traces appear without any ASGI integration. With traces_sample_rate above zero you get per-tool performance data; with enable_logs and the LoggingIntegration, the per-call log records land in Sentry Logs.

What to look at in Sentry:

• Performance -> transactions named admin_<tool>, op mcp.tool: who calls what, how often, and how long it takes, filterable by the mcp.model, mcp.client, and mcp.outcome tags and by user.

• Metrics: damf.<tool>.ok / .denied / .error counters and damf.<tool>.duration_ms distributions, for dashboards and alerts (a spike in .denied is an agent probing where it should not).

• Issues: real exceptions from tool calls, with the user, client, and tool tags attached. Denials are not issues; they are the system working.

For Logfire, call logfire.configure() in settings.py; the package stays silent until then, because an unconfigured logfire warns on every span.

Two settings knobs, both default true, turn a backend off without uninstalling it: ENABLE_SENTRY_TRACING and ENABLE_LOGFIRE_TRACING.

Deployment

The MCP endpoint runs as its own process, next to your Django application:

python manage.py admin_mcp_serve

It serves the path from MCP_URL on the port in MCP_URL, or 8765 when that URL names no port. --host and --port override both. Nothing about how you already serve Django changes. The process is stateless, so any replica can serve any request.

It needs its own process because FastMCP starts the streamable-HTTP session manager from the ASGI lifespan. A project that serves with lifespan disabled, which is common for Django, cannot host the MCP app inside its own ASGI application: the session manager never starts and every call fails. admin_mcp_serve runs its own server with lifespan enabled.

Behind a reverse proxy

If you already route by path to separate worker pools, this is one more pool. Send the MCP path to the MCP process and leave every other path where it is. Three rules matter.

Match the exact path, never the prefix. The OAuth endpoints sit directly below the same prefix (/admin/mcp/authorize, token, register, revoke), and Django must keep serving them, because the consent page rides the admin session cookie. A prefix rule hands them to the MCP process, which knows nothing about them, and no client can ever authorize. Keep /.well-known/oauth-authorization-server on the Django pool too.

Pass the Authorization header through. The transport authenticates with a bearer token, so a proxy that strips or rewrites that header denies every call.

Do not apply an idle-read timeout to this route. Responses are event streams. A short read timeout severs a tool call that thinks between writes.

Caddy, where the exact matcher comes first because same-directive routes keep their file order:

# The MCP endpoint. Exact path, so /admin/mcp/authorize stays with Django.
@mcp path /admin/mcp
reverse_proxy @mcp myapp_mcp:8000

# The admin, including the OAuth endpoints under /admin/mcp/.
@admin path /admin /admin/*
reverse_proxy @admin myapp_admin:8000

nginx, where location = is the exact match and wins over the prefix:

location = /admin/mcp { proxy_pass http://myapp_mcp:8000; }
location /admin/      { proxy_pass http://myapp_admin:8000; }

With the route in place, MCP_URL is your public site URL plus the path, and the port stays private:

ADMIN_FASTMCP = {
    "SITE_URL": "https://app.example.com",
    "MCP_URL": "https://app.example.com/admin/mcp",
}

Both values are public URLs, so derive them from whatever setting already holds your site's canonical URL rather than writing them twice.

Under your own server

admin_mcp_serve is uvicorn with one setting that matters: lifespan="on". Any ASGI server works, as long as it runs the lifespan. Expose the app in a module of your own:

# myproject/asgi_mcp.py
import os

os.environ.setdefault("DJANGO_SETTINGS_MODULE", "myproject.settings")

import django

django.setup()

from django.conf import settings
from django_admin_fastmcp.server import BodySizeLimit, build_server

application = BodySizeLimit(build_server().http_app(stateless_http=True, path="/admin/mcp"))

Then serve it the way you serve the rest of your fleet, with lifespan enabled:

granian --interface asgi --host 0.0.0.0 --port 8000 myproject.asgi_mcp:application
uvicorn --lifespan on --host 0.0.0.0 --port 8000 myproject.asgi_mcp:application

Granian's asginl interface, and uvicorn --lifespan off, both skip the lifespan. A Django project often chooses one of those for its own app, because Django implements no lifespan. This app is the opposite: skip the lifespan and the session manager never starts, so every call answers RuntimeError: Task group is not initialized.

Mounted in your ASGI application

Possible, and rarely worth it. It needs a parent lifespan that drives the FastMCP session manager, plus a dispatcher on the exact path for the reason above. A separate pool needs neither, and gives you independent restarts and scaling: an agent that hammers the tools cannot starve the workers serving people.

Development

make install     # bootstrap uv, pin Python, install dependencies
make test        # run the permission matrix
make check       # format, lint, typecheck, and test
make migrate     # migrate the test project
make serve       # run the MCP server against the test project on :8765/admin/mcp
make help        # everything else

License

MIT