easyapi

A framework I built for myself. It gives you a production MCP server and a REST API on top of Django models. Both surfaces reuse the same engine — auth, rate limiting, edge security, sensitive-field scrubbing and multi-tenant DB routing. REST and MCP each get a dedicated, well-shaped surface — they're no longer welded together. If you don't have Django, easyapi init reads a MySQL or Postgres schema and generates the whole project.

I run it in six of my own products. Sharing it because I'd like help making it better — issues, PRs, and "this broke for me" reports are all welcome.

Install

pip install easyapi-django                   # framework only
pip install 'easyapi-django[gen-mysql]'      # + generator for MySQL
pip install 'easyapi-django[gen-postgres]'   # + generator for Postgres

The PyPI distribution is easyapi-django. Imports use from easyapi import .... The CLI is easyapi.

What it looks like

REST resources are one class. MCP toolsets are another. They reuse the same engine primitives — auth (BaseResource._authenticate), rate limiting (easyapi.rate_limit), sensitive-field scrubbing (easyapi.sensitive), multi-tenant DB routing (aset_tenant, activated during auth via apply_session_to_request on both surfaces) and the global SecurityMiddleware. Both classes inherit a common CoreResource base — today a thin seam, not a policy layer.

REST — BaseResource exposes a Django model as a CRUD endpoint:

from easyapi import BaseResource
from myapp.models import Space

class SpaceResource(BaseResource):
    model = Space

That class gives you:

REST endpoints (GET, POST, PATCH, DELETE) with pagination, filters, search, ordering.
OpenAPI 3.0.3 spec at /openapi.json and an interactive docs page at /docs.
Async dispatch, session + API-key + Bearer auth, per-IP rate limit, scanner blocking, multi-tenant DB routing.

MCP — Tools collects intent-named methods into an MCP tool registry. Type hints become JSON Schema (Draft 2020-12); docstrings become tool descriptions for the agent:

from typing import Literal
from pydantic import BaseModel
from easyapi import Tools, tool

class OrderOut(BaseModel):
    id: int
    status: str

class Orders(Tools):
    scope = "orders:read"

    async def find(
        self,
        status: Literal["open", "closed"] | None = None,
        limit: int = 50,
    ) -> list[OrderOut]:
        """List the caller's orders, optionally filtered by status."""
        qs = Order.objects.filter(owner_id=self.user_id)
        if status:
            qs = qs.filter(status=status)
        return [OrderOut.from_orm(o) async for o in qs[:limit]]

    @tool(scope="orders:write", destructive=True, rate_limit="10/m")
    async def cancel(self, order_id: int, reason: str) -> OrderOut:
        """Cancel an order and refund the original payment method."""
        order = await Order.objects.aget(pk=order_id)
        await order.cancel(reason)
        return OrderOut.from_orm(order)

Tools surface as <namespace>_<method> — orders_find, orders_cancel. The framework follows the MCP client name regex ^[a-zA-Z0-9_-]{1,64}$ (dots aren't accepted by Claude.ai). The namespace defaults to the lower-cased class name, trimmed of a trailing tools (so OrdersTools → orders); override via namespace = '...' on the Toolset.

Wire both surfaces in urls.py:

from easyapi import get_routes

urlpatterns = get_routes(
    endpoints={r'orders(.*)$': OrderResource},
    toolsets=[Orders, Billing],
)

You get /orders… for REST, /mcp for JSON-RPC, /openapi.json, /docs, /mcp/tools (browseable) and /mcp/tools.json (machine-readable).

If you don't have Django yet:

easyapi init

The CLI prompts for host, db, credentials. About ten seconds later you have a working Django project — every table is a model with a REST resource. Sensitive columns (password, token, api_key) are auto-masked. Read-only by default. Pass --writable when you mean it. Write your MCP tools as Tools subclasses on top of the generated models.

Why it exists

Two years ago I got tired of writing the same Django REST API for the tenth time — DRF, Ninja, FastAPI, all powerful, all the same boilerplate. So I wrote a small framework for myself: one class, set some attributes, get the endpoints. I called it easyapi.

When MCP showed up and every project I had needed an agent surface, I expected to write a second codebase. Instead the MCP server fell out of the same engine in a weekend — auth was already there, rate limit was already there, the field whitelists were already there. Only the wire format changed.

REST is mostly a solved problem now. The new pain is MCP — most teams are rebuilding the same scaffolding. So I cleaned up easyapi and put it on GitHub — same engine, now with a first-class MCP surface.

What you get

REST (BaseResource)

Async CRUD on Django models with pagination, filters, search, ordering.
OpenAPI 3.0.3 spec + Scalar UI.
Cache with namespace invalidation. Writes don't blow away unrelated rows.
Ownership scoping. One attribute (owner_field = 'owner_id') restricts every CRUD operation to rows owned by the authenticated user — the cheapest IDOR defense I know.

MCP (Tools + MCPServer)

Intent-named tools: each public method is a tool; _underscore methods stay private. Helpers that must stay public-but-non-tool go in excluded_methods = (...).
JSON Schema (Draft 2020-12) generated from type hints; raw schema escape hatch when you need it (@tool(input_schema={...})).
Docstrings become tool descriptions for the agent — the full docstring is published, not just the first line.
MCP annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) via @tool(...). Read-scoped tools get readOnlyHint + idempotentHint automatically; override per-method when needed.
Per-tool scope and rate_limit ('10/m' shorthand or {'limit': N, 'window': seconds}). tools/list filters by the caller's OAuth scope so an agent only sees what it can call.
Class-level default_output_schema (set to False when methods return free-shape dict so the agent isn't misled by an auto-derived loose schema).
Pinned envelope: {tool, code, data} on success; {tool, code, message, ...} on error. Error codes are stable strings: OK, VALIDATION_ERROR, NOT_FOUND, FORBIDDEN, INSUFFICIENT_SCOPE, RATE_LIMITED, METHOD_NOT_ALLOWED, INTERNAL.
before_call / after_call hooks for audit and membership preloading.
MCPTestClient drives the registry in-process — unit tests don't need HTTP.

Shared engine — reused by both surfaces (not held on the CoreResource base, which is an empty seam today):

Bearer + X-Api-Key + session-cookie auth. (MCP calls BaseResource._authenticate via MCPServer.)
Pre-auth per-IP throttling, scanner blocking and semantic invalid-request detection — via the global SecurityMiddleware, so both surfaces are covered.
Sliding session TTLs via Redis GETEX. Configure with SESSION_TTL (default 1800s) and API_SESSION_TTL (default 300s).
Sensitive-field scrubbing (password, api_key, token baseline plus your additions) — applied on both REST and MCP responses (each surface scrubs with its own serializer over the shared is_sensitive).
Multi-tenant DB routing. apply_session_to_request is the single activation authority: Bearer, API-key and Redis-loaded sessions reach it inside _authenticate; a session already on the request was applied earlier by AuthMiddleware. Either way the connection is switched for the request on both surfaces.
Async end-to-end. Async ORM, async Redis, async dispatch.

REST-only — enforced in BaseResource._dispatch:

Authenticated abuse blocking by tenant/user or API-key digest.

Global read-only mode — EASYAPI = {'READ_ONLY': True} rejects every non-GET REST request with 405; for MCP it allows only tools classified as read-only (a read scope or @tool(read_only=True)) and rejects all other tools/call requests with METHOD_NOT_ALLOWED.

Full docs and reference: https://github.com/ssjunior/easyapi-django

Connecting an agent

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "myapp": {
      "command": "python",
      "args": ["manage.py", "mcp_serve", "myapp.mcp.toolsets"],
      "cwd": "/path/to/your/project",
      "env": {
        "DJANGO_SETTINGS_MODULE": "myapp.settings"
      }
    }
  }
}

myapp.mcp.toolsets is a module-level sequence of Tools subclasses, e.g. toolsets = [Orders, Billing]. Restart Claude Desktop. The agent now sees every tool you declared.

For HTTP-based agents (Cursor, custom copilots, anything else that speaks JSON-RPC over POST), the same tools live at POST /mcp. Auth is whatever you've wired into your BaseResource stack — Bearer, X-Api-Key, or session cookie all work; per-tool scopes filter tools/list automatically.

curl -X POST http://localhost:8000/mcp \
  -H 'Content-Type: application/json' \
  -H "X-Api-Key: $TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

When this isn't the right tool

I'd rather you bounce now than get stuck a month in.

No Redis available. Sessions, cache, rate limit and abuse blocking all rely on it. Redis 6.2+ (uses GETEX for sliding session TTLs). Non-negotiable.
You need complex auth. OAuth2 server, SAML, intricate permission matrices — DRF or a custom stack will fit better.
Your endpoints are mostly RPC, not CRUD. And you don't want them as MCP tools either.
You don't want Django. easyapi wraps the Django ORM. The init command generates a Django project. If that's a dealbreaker, this isn't your tool.
You want a big plugin ecosystem. It's small on purpose.

Hardening before you ship

Defaults are demo-friendly. Production deployments should:

Cookie auth. Set at least one of ENFORCE_TOKEN = True (HMAC anti-replay on state-changing requests) or ALLOWED_ORIGINS = [...] (Origin allowlist). Without either, the framework logs a startup warning — there is no built-in CSRF defense for POST/PATCH/DELETE.
Per-resource ownership. Set owner_field = 'owner_id' on resources where rows belong to a single user — restricts every CRUD operation to the row's owner. POST always forces owner_id to the caller (override with allow_owner_override = True for admin paths).
Authenticated cache. If you turn on cache = True for an authenticated resource, set session_cache = True or cache_scope_fields = (...) — otherwise responses can leak across users. The framework warns at runtime when it detects this combination.
Tune session TTLs. SESSION_TTL (cookies, default 1800s) and API_SESSION_TTL (api-key cache, default 300s) both slide on use. Pick numbers that match your security/UX trade-off.
Never ship DEBUG = True. Under DEBUG, edge security (scanner blocking, semantic invalid-request detection), rate limiting, credential-path defense and abuse blocking are all bypassed for dev ergonomics. The framework logs a loud startup warning when the bypass is active. To decouple from DEBUG — e.g. a staging box mirroring production — set EASYAPI = {'SECURITY_BYPASS': False} to force protections on (or True to bypass without DEBUG).
Trust your proxies explicitly. Pre-auth throttles, scanner blocking and anonymous abuse detection key on the client IP. X-Forwarded-For / X-Real-IP are only honored when REMOTE_ADDR is in TRUSTED_PROXIES = ['10.0.0.0/8', ...]; otherwise REMOTE_ADDR wins. Leave it unset behind a proxy and every request looks like it comes from the proxy.
Authenticated blocks follow the principal. The fast pre-auth throttle, login defense and path/User-Agent scanner signatures remain IP-based. After successful authentication, semantic events and sustained abuse use a tenant-scoped user digest or API-key digest; anonymous requests keep using IP. This prevents one authenticated user behind a shared NAT from blocking everyone else while still stopping the same principal after an IP change.
Bound external Bearer resolvers. Query-contract failures are attributed after authentication, so an unknown/protected parameter carrying a Bearer token can invoke BEARER_RESOLVER before the request is rejected. The default NO_RESOLVER path performs no external call. Custom network-backed resolvers should enforce a short timeout, cache safely where appropriate, and be latency/load-tested behind the pre-auth IP throttle.
/metrics is opt-in. get_routes doesn't mount it unless you pass metrics_view=Metrics (the generic, unscoped resource — from easyapi import Metrics) or a custom row-scoped subclass. Once mounted, bound which models it can query: set METRICS_MODELS = ['app_Model', ...] to allowlist them. References to credential-named columns (in filters, groups, order or calc) are always rejected regardless — the per-resource escape hatch does not reach /metrics.
Bound the metrics fields, per model. METRICS_MODELS only gates which models — every non-credential field on an allowed model is still fair game for /metrics (filter, group, order, calc), including arbitrary FK traversal. Set METRICS_FIELDS = {'app_Model': ['status', 'owner__name', ...]} to also allowlist which field paths, per model. Unlike REST's filter_fields (root-segment match), this checks the full __-joined path — 'owner' in the list does not imply 'owner__anything' is allowed. filter_by references tolerate one trailing Django lookup (owner__name__icontains matches an allowed owner__name) since those reach Q(**kwargs) directly; calc/group_by/order/additional_fields/conditions don't take lookups and are matched literally. A model absent from the dict, or the setting left unset, stays unrestricted — opt-in, same as METRICS_MODELS. If you already maintain a bi_fields/related_fields map for a frontend field picker, easyapi.util.flatten_include_fields(model, bag) turns that same data into the flat path list this setting expects, so there's one source of truth instead of two.
Keep the escape hatch narrow. Columns whose names look like credentials (password, api_key, token, otp, secret, …) are masked as '*********' on every response, on top of whatever sensitive_fields lists. When the heuristic catches a false positive, opt it out per surface: edit_allow_sensitive_fields = ['token_count'] returns it verbatim on GET /resource/<id>/ while LIST still masks it. list_allow_sensitive_fields does the same for LIST, where every row carries the value — reach for the detail-only form first.
Keep query capabilities separate. Query-string names outside the framework contract are rejected. Declare custom names in extra_query_params. A protected name allowed in a LIST response through list_allow_sensitive_fields is still forbidden as a direct/JSON filter; add it separately to allow_protected_query_fields only when filtering by that value is intentional. Existing resources using the response escape hatch may need this explicit filter capability after upgrading.
OAuth clients are public by default. MCP clients (Claude.ai, ChatGPT, ...) authenticate with PKCE — list them under EASYAPI['OAUTH_CLIENTS'] with no client_secret. A client becomes confidential only with an explicit secret; /register never hands out a confidential secret (provision those out of band).

Help wanted

If you try it and something breaks, please tell me. The kinds of help that make this better:

Bug reports. Open an issue with what you tried and what happened. Including the Python/Django version helps.
PRs. Small ones welcome. For larger changes, open an issue first so we can talk through the shape.
"This is confusing" feedback on the docs. The doc site needs more eyes.
Sharing how you use it. I'm curious what shapes of projects this actually lands in.

There's no CLA, no contributor matrix, no roadmap voting. Just open an issue and we figure it out.

Project

Author — Stamatios Stamou Jr
License — MIT
Python — 3.10+
Django — 5.0+
Repo — github.com/ssjunior/easyapi-django

Framework
- Django
Intended Audience
- Developers
Operating System
- OS Independent
Programming Language
- Python :: 3
Topic
- Software Development :: Libraries :: Python Modules

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

easyapi_django-1.5.1.tar.gz (160.7 kB view details)

Uploaded Jul 21, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

easyapi_django-1.5.1-py3-none-any.whl (184.1 kB view details)

Uploaded Jul 21, 2026 Python 3

File details

Details for the file easyapi_django-1.5.1.tar.gz.

File metadata

Download URL: easyapi_django-1.5.1.tar.gz
Upload date: Jul 21, 2026
Size: 160.7 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.1.0 CPython/3.12.1

File hashes

Hashes for easyapi_django-1.5.1.tar.gz
Algorithm	Hash digest
SHA256	`fefb820fd0ac7925478d1f8ebf99885ac0cf5123192e486a479823808a43656b`
MD5	`3085a9884a680a0fa6438868e4c00492`
BLAKE2b-256	`fef463b083b541a117f23f913ebc6d4022bd15ec6ab756912a0cf31fb5216ff7`

See more details on using hashes here.

File details

Details for the file easyapi_django-1.5.1-py3-none-any.whl.

File metadata

Download URL: easyapi_django-1.5.1-py3-none-any.whl
Upload date: Jul 21, 2026
Size: 184.1 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.1.0 CPython/3.12.1

File hashes

Hashes for easyapi_django-1.5.1-py3-none-any.whl
Algorithm	Hash digest
SHA256	`5a6e908b16caf4b8ed1a3d3fd4ba0fac79a9c242b69762466465511ae40a64af`
MD5	`030f22a8153286b0b8401bccd64a8c79`
BLAKE2b-256	`53bcdeddb447e2a098bbc66e042aa79047bd48846bf080dda2f0e4d13bc670e1`