sett-mcp

Python MCP servers that are read-only until you say otherwise. One command gives you a working server on the official MCP Python SDK v2, with guardrails that are tested and on by default.

uvx sett-mcp new my-server

A sett is a badger's den, dug deep and hard to break into. Setts are also the square stones that pave a solid road.

Why

Connecting an AI assistant to a real system is easy. Being comfortable leaving it connected is the hard part: what happens when the model decides to "clean up" some records? Most MCP starters give you a tool decorator and leave the rest to you. This one starts from the question your ops or security lead will ask.

Related MCP server: MCP Mingdao

What you get

Plus the plumbing that usually takes an afternoon:

• A runnable example (a small contacts store) you replace with your real API client

• install <client> for Claude Desktop, Cursor, Claude Code and Codex, with --writes to turn write tools on, and a troubleshooting guide in every project

• Stdio by default, stateless Streamable HTTP with serve --http, tested against the edge cases that break real clients

• Remote in one command: deploy vercel --auth supabase hosts the server on your own Vercel account with Supabase for sign-in: a consent page, invite-only users, a writer role for write tools, confirmations that work across server instances, and an audit table. Remote mode also works with any OAuth provider on any host

• Setup instructions for Claude Desktop, Claude Code, Cursor, the MCP Inspector and Docker

• Tests that drive the server through a real MCP client on both protocol versions

• GitHub Actions for CI and PyPI publishing, so users can run uvx your-server

• A Dockerfile, glama.json and a publishing guide for PyPI, Glama, the awesome-mcp-servers list and the official MCP Registry

• A CLAUDE.md that keeps Claude Code from bypassing the guardrails when it adds tools, and shows it how to describe tools well

Quick start

uvx sett-mcp new my-server
cd my-server
uv sync
uv run --extra dev pytest                  # the guardrail test suite
uv run my-server install claude-desktop    # or cursor, claude-code, codex, all; then restart it

To host it for others, with sign-in, on your own Vercel and Supabase accounts:

uv run my-server deploy vercel --auth supabase --supabase-project <ref>
uv run my-server users add you@example.com --writer

Copier asks for a name, tool prefix and environment-variable prefix. Everything else is filled in. New to this? docs/getting-started.md walks through it from installing uv, on Windows and macOS.

Adding a tool looks like this:

@guard.read(name="acme_list_invoices")
async def list_invoices(status: str = "open") -> list[dict]:
    """List invoices by status."""
    return await api.invoices(status=status)

@guard.write(name="acme_void_invoice", destructive=True,
             confirm_message="Void invoice {invoice_id}? This can't be undone.")
async def void_invoice(invoice_id: str) -> dict:
    """Void an invoice."""
    return await api.void(invoice_id)

Client support

Tested in November 2026 with the example server this template generates:

What that means in practice:

• A confirmation is only as strong as the client. Sett can't tell a person clicking Accept from a client that accepts automatically. The write gate and the allow / deny lists don't depend on the client at all, so treat those as the hard limits.

• Where prompts can't reach (local servers in Claude Desktop today), keep the default confirm: destructive, or deploy the server remotely so the prompt can be shown: deploy vercel --auth supabase --supabase-project <ref> --writes, give the person the writer role with users add <email> --writer, and add the /mcp address as a connector. Without --writes, write tools aren't registered at all. Ordinary writes still work, and destructive ones are refused. Setting confirm: off makes them run without asking.

• Claude may refuse on its own. In our tests Claude sometimes declined to call a tool described as permanently deleting data, or asked in chat first. That's a welcome extra layer, but it depends on the model and the conversation, which is why the server enforces confirmation itself.

Tried another client? Open an issue with what you saw and we'll add it to the table.

Keeping generated projects current

Guardrail fixes and SDK updates land here. Pull them into any project made from the template with:

uvx sett-mcp update

sett-mcp is a thin wrapper around Copier, so uvx copier copy gh:kclarkedesign/sett-mcp my-server and copier update work too.

Migrating from FastMCP v1

SDK v2 renamed FastMCP to MCPServer and changed a dozen other things. See docs/migrating-from-v1.md for the checklist and how to move a hand-rolled write gate onto the guardrails.

Roadmap

• A preflight sett-mcp check that tests a running server against real clients' quirks

• One-click .mcpb bundles for Claude Desktop

• More deploy targets: Cloudflare Workers, Cloud Run, Fly

• Example connectors, starting with a read-only Salesforce analyst server

Contributing

Issues and pull requests are welcome. To work on the template itself:

uvx copier copy --trust --defaults --vcs-ref HEAD . /tmp/check
cd /tmp/check && uv run --extra dev pytest

License

Apache-2.0. Projects you generate can choose Apache-2.0 or MIT. Logo and icon files are in assets/, including an animated reveal and a looping loading mark (rebuild them with node scripts/build_motion.mjs).