The Python MCP Server Your AI Agent Already Understands
Django and FastMCP, with 673 lines of architectural contract your coding agent reads before it writes anything. One folder is yours to extend. Billing, API keys, OAuth and rate limits sit behind a boundary your agent is told not to cross.
Every paid API burns the same month before feature one
Auth. Magic links, hashed API keys, and OAuth 2.1 with PKCE: the flow Claude.ai demands before it will even connect.
Billing. Stripe webhooks, a credit ledger that survives race conditions, refunds when your code throws.
Rate limits, dashboards, call logs, docs pages, deploy configs. Still zero endpoints shipped.
This is the codebase you wish you'd started with: all of it wired and tested, so day one is your actual product.
Your agent gets one folder to write in, and 673 lines telling it what goes there
Not a README it might skim. CLAUDE.md is loaded as Claude Code's project context on every session, and it opens by fencing off the fourteen apps that run your billing, your API keys and your OAuth.
# CLAUDE.md — architectural contract
This file is the architectural contract for the
codebase. It is also loaded as Claude Code's project
context, so AI assistants read it on every session.
⋮
## Where you can and cannot edit
(the framework boundary)
✅ apps/app_endpoints/ ← add your endpoints here
❌ apps/core/ ← framework (registry, ctx,
rest, http, resilience)
❌ apps/billing/ ← framework (Stripe + credits
+ ledger)
❌ apps/plans/ ← framework (Plan /
UserSubscription /
entitlements)
❌ apps/api_keys/ ← framework (key mint / hash
/ auth_backend)
❌ apps/mcp_oauth/ ← framework (OAuth 2.1 + DCR
+ IATs)
⋮
❌ apps/docs/ ← presentation
If you find yourself needing to edit a framework app
to make your endpoint work, an extension point is
missing.The boundary map gives your agent apps/app_endpoints/ and marks fourteen framework apps off-limits, billing, API keys and OAuth among them. Three of those boundaries are machine-enforced too: import-linter fails CI on the import rules that would blur them.
The authoring recipe numbers them, with the exact file names at each step. Step 0 tells your agent to ASK you whether your provider supports webhooks rather than choose for you, because switching that decision later is a refactor.
Five complete endpoints ship under apps/app_endpoints/, covering the sync, credit-charging, background-job and webhook-completion shapes. Your agent copies one that exists instead of inventing a sixth.
A lookup table naming the exact module for eleven questions an agent would otherwise guess at, from how the REST view dispatches a request to where the credit charge actually happens.
Every system you'd build yourself — already wired up
Pick a system to see what's done. Endpoints, MCP, auth, billing, dashboards, and ops ship working. 1,088 tests say so.
One Class, Three Surfaces
Auth & Access
Billing & Credits
Dashboards
Ops & Reliability
Developer Experience
Real screens, not mockups
Every screen below is the boilerplate running unmodified. Tap through the tour.
The Try-it panel firing a real call and returning a QR code The endpoint catalog your customers browse Customer dashboard: plan, credits, and every call logged API keys your customers mint, preview, and revoke themselves Claude calling a tool you wrote as one Python class Usage analytics: credits burned, error rates, per-endpoint latency
This template vs. the alternatives
Against wiring it yourself, TypeScript MCP skeletons, or renting a metering gateway that takes a cut.
| Feature | This template | Build from scratch | Generic boilerplate |
|---|---|---|---|
| One class → REST + MCP tool + docs page | |||
| Credits auto-charged, refunded on errors | |||
| Stripe subscriptions + credit packs wired | |||
| One-click Claude.ai OAuth connect | |||
| Customer dashboard + operator console | |||
| Per-plan rate limits + quota alerts | gateway only | ||
| You own the stack, no per-call cut | |||
| Python / Django, not a TS skeleton | - | ||
| Proven in production (ToolerBox) | |||
| Time to first PAID endpoint | ~1 day | ~4-6 weeks | ~2 weeks |
You'll get the most out of it if…
Solo builders selling their first API
You have the endpoint idea. You do not have a month for auth, billing, and MCP plumbing. Skip to the product.
Builders riding the MCP wave
Every AI assistant can call your product over MCP. Ship the tool; the protocol, OAuth, and metering are done.
Teams adding a paid API surface
Bolt a metered, documented API + MCP layer next to your existing product without inventing billing twice.
People who build with AI
You describe the endpoint and check four things. CLAUDE.md keeps Claude Code and Cursor inside your folder and out of the billing code.
Buy it solo — or bundled and save
Just this boilerplate, or a bundle that unlocks the courses and every other boilerplate too.
Django and FastMCP boilerplate for Claude Code: one Python class becomes a REST endpoint, an MCP tool and live docs, with billing, credits and OAuth wired. The stack behind ToolerBox.
- Python MCP Server Boilerplate $79
- Lifetime access to all updates
The course + all 4 boilerplates.
- Build With AI 1.0Course $149
- Desktop App Boilerplate $49
- Python MCP Server Boilerplate $79
- Mobile App Boilerplate $59
- Django Web App BoilerplateComing $49
- Private Discord community $99
- Lifetime access to all updates
Every course, boilerplate, and product I build, in one bundle.
- Build With AI 1.0Course $149
- Self Hosting 2.0Course $69
- Business Ideas LibraryComing $49
- Desktop App Boilerplate $49
- Python MCP Server Boilerplate $79
- Mobile App Boilerplate $59
- Django Web App BoilerplateComing $49
- Private Discord community $99
- Lifetime access to all updates
Frequently asked questions
What exactly do I get when I buy?
An invite to the private GitHub repository with the full source: 740 files, 1,088 passing tests, 20 Django apps, 5 worked example endpoints, and 30 reference docs, plus lifetime updates via git pull, and step-by-step public docs that take you from clone to a deployed, paid, Claude-callable API.
What is the license?
Single-app commercial license, in plain English: build and sell ONE commercial product per purchase, with unlimited learning projects and prototypes on top. Modify anything, keep your fork private, deploy anywhere. The only hard rule is you cannot republish or resell the template itself. Everything you build on it is yours.
How good at Python do I need to be?
The walkthrough docs assume none of it: Docker runs everything (you never install Python), and the first endpoint you build is one you describe to Claude Code rather than type. The docs give you the prompt and the four things to check in what comes back, and the whole class is about 20 lines you can read in one sitting. Developers get a full dev setup and a 1,088-test suite on top.
Can I really build endpoints with Claude Code, or is that just marketing?
The repo ships 673 lines of CLAUDE.md that Claude Code loads as project context on every session: a 6-step endpoint recipe, five worked endpoints to copy, an 11-row lookup table pointing at the module that answers each common question, and a boundary marking the fourteen framework apps your agent must not edit. The public docs walk you through building a QR-code endpoint that way, prompt first, and the reply shown on that page is the unedited one from a clean clone. Cursor and Copilot work too; they just need telling to read the file, because they do not load it by convention.
Do I need Stripe to start?
No. The credit system works standalone: you grant credits from the admin console and the framework enforces balances, charges per call, and refunds errors. Connect Stripe later and users buy subscriptions and credit packs themselves. There is a documented credit-only mode if you never want Stripe at all.
How do my users connect it to Claude?
Three built-in ways: one-click OAuth from Claude.ai (they click Connect and approve on your domain (the OAuth 2.1 + PKCE + registration dance is done for you), API keys for developers and Cursor, and URL-token addresses for clients that cannot send headers. All three hit the same credits and rate limits.
What do I need installed to run it?
Docker Desktop and Git. That is the whole list: one script boots the API, MCP server, worker, Postgres, and Redis (measured: 58 seconds from fresh clone to healthy on a warm machine). Python on your machine is optional, for developers who want the test suite.
Is this actually used in production?
Yes: ToolerBox.com sells its API + MCP layer on this exact boilerplate: credit-metered endpoints, async jobs, OAuth connects from Claude, real customers. The template is the generalized version of that production stack, and every walkthrough doc was executed end-to-end (including a real VPS deploy) before publishing.
How do updates work?
The private repo is the distribution channel: git pull brings every improvement. The changelog marks [SECURITY] entries as pull-within-a-week and [BREAKING] entries ship with exact upgrade steps in UPGRADING.md, including the fork conflict-resolution playbook.
Stop wiring plumbing. Start selling endpoints.
$79 once. Lifetime updates. One commercial app.
Get Python MCP Server Boilerplate →