frisian-mcp

The Django MCP gateway that discovers your API automatically.

frisian-mcp turns your existing Django REST Framework ViewSets into Model Context Protocol tools with zero boilerplate. Add the package, include one URL, and every ViewSet action becomes a callable MCP tool — name, description, and input schema derived from your serializers automatically.

Designed for token-efficient agent workflows. A 50-action Django app loads in 500–2,000 tokens of tools/list schema instead of the 15,000–25,000 conventional flat MCP would emit; a 60-device bulk-write response is 24 tokens instead of ~10,800 of full echo. Same surface, two orders of magnitude less context burned before the agent has done any reasoning. Full numbers in Token efficiency.

Version: 1.1.1 | License: Apache 2.0 | Python: 3.11+ | Django: 5.x

pip install frisian-mcp

Project site: https://frisian-mcp.com/

A live MCP server is hosted at https://frisian-mcp.com/ for hands-on evaluation — point any MCP-compatible client at it to see the dispatcher pattern and lean envelope behavior against a real surface. The same site serves the project documentation through an MCP-consumable dispatcher, so coding agents (Claude Code, Codex, Gemini CLI, etc.) can connect to it directly and consume installation, configuration, and decorator reference material as part of their working context while integrating frisian-mcp into your own project.

At a glance

Token efficiency

The dispatcher pattern and the lean write envelope exist for one reason: agent context windows are finite, and the conventional MCP shape (one tool per ViewSet action; full serialized echo on every write) burns through that budget before the agent has done anything useful.

Measured numbers from real integrations:

The bulk-write savings are constant regardless of batch size — the lean envelope is fixed-shape and the full response is reachable via the continuation token without re-running the write. The dispatcher reduction is opt-in through FRISIAN_MCP_DISPATCH_GROUPS (autodiscovery alone gives the conventional flat shape).

See The Token Problem, Dispatcher Pattern, and Write-Path Response Filtering for the design rationale and full measurements.

Requirements

• Python 3.11+
• Django 5.x
• Django REST Framework 3.14+

Quickstart

1. Install and add to INSTALLED_APPS:

# settings.py
INSTALLED_APPS = [
    ...
    "frisian_mcp",
]

2. Include the gateway URL:

# urls.py
from django.urls import include, path

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

That's it. With auto-discovery enabled (the default), every DRF ViewSet in your URL tree is now an MCP tool.

# myapp/views.py — nothing changes here
class UserViewSet(viewsets.ModelViewSet):
    queryset = User.objects.all()
    serializer_class = UserSerializer
    permission_classes = [IsAuthenticated]

After startup, the gateway exposes users.list, users.retrieve, users.create, users.update, users.partial_update, and users.destroy — derived entirely from the ViewSet.

3. Generate a client config:

python manage.py mcp_config --token mytoken123

{
  "mcpServers": {
    "frisian-mcp": {
      "url": "http://localhost:8000/mcp/",
      "transport": "http",
      "headers": { "Authorization": "Bearer mytoken123" }
    }
  }
}

Use --client to emit the format expected by a specific MCP client. Use --url and --name to override the server URL and key.

4. Verify the install:

python manage.py mcp_doctor                # standard audit
python manage.py mcp_doctor --security     # extended OAuth security audit

Walks the configuration end-to-end and exits non-zero on errors. Run after every install, every config change, and as the first diagnostic step on any unexpected behaviour. See the mcp_doctor guide for the full check list.

Architecture overview

MCP Client
       │  JSON-RPC 2.0 over HTTP POST
       ▼
┌──────────────────────────────────────────────────┐
│  McpView  (DRF APIView)                           │
│  ├─ Authentication  (FRISIAN_MCP_AUTHENTICATION_CLASSES) │
│  ├─ Permissions     (FRISIAN_MCP_PERMISSION_CLASSES)     │
│  └─ Method dispatch                              │
│       ├─ initialize / initialized / ping / help  │
│       ├─ tools/list  ──────────────── ToolRegistry │
│       ├─ tools/call  ── ToolMiddleware ── Registry │
│       ├─ resources/list ───────── ResourceRegistry │
│       └─ resources/read ───────── ResourceRegistry │
└──────────────────────────────────────────────────┘
       │
┌──────────────────┐   ┌─────────────────────────┐
│  ToolRegistry    │   │  Auto-discovery          │
│  (module-level   │◄──│  (DRFSyncDiscovery)      │
│   singleton)     │   │  Walks URL patterns at   │
│                  │   │  AppConfig.ready()       │
└──────────────────┘   └─────────────────────────┘
       │
┌──────────────────────────────────────────────────┐
│  InvocationBackend  (SyncInvocation by default)  │
│  Builds synthetic DRF Request → calls ViewSet    │
│  action → returns ToolResult                     │
└──────────────────────────────────────────────────┘

• Separation of discovery and invocation. Two pluggable backends — override either independently.
• Registry is the source of truth. @mcp_tool, @mcp_dispatcher, and auto-discovery all write to the same tool_registry singleton.
• Tool errors are isError: true, not JSON-RPC errors. Permission denials and handler exceptions return isError: true inside a normal HTTP 200 response — the session stays alive.
• Two enforcement points. Gateway-level permissions gate the entire /mcp/ surface. Tool-level tiers gate individual tools/call invocations.

Dispatcher pattern

For teams building purpose-built agent tools, frisian-mcp ships the @mcp_dispatcher pattern: one MCP tool name routes to many actions internally.

from frisian_mcp import mcp_dispatcher, mcp_action

@mcp_dispatcher(name="tasks", description="Manage project tasks.")
class TasksDispatcher:

    @mcp_action(name="create", description="Create a task.")
    def create(self, request, params):
        task = Task.objects.create(title=params["title"])
        return {"id": task.pk}

    @mcp_action(name="list", description="List tasks by status.")
    def list(self, request, params):
        return {"tasks": list(Task.objects.values("id", "title", "status"))}

One tool in tools/list instead of many. Call with action="help" for a structured listing of available actions. Per-action JSON Schema validation runs before the method.

This is the pattern for agent-facing APIs where tool count matters and progressive disclosure beats a flat list.