© 2026 Jonathan Freire

Released under the MIT License

MCPStack
Log inSign up

MCPStack

The production-ready foundation for agent-native SaaS. Identity, permissions and the MCP server your agents talk to are already wired, so the first days go into your product.

git clone https://github.com/jonathanfreiredev/mcp-stack && cd mcp-stack cp .env.example .env && cp backend/.env.example backend/.env cp frontend/.env.example frontend/.env && docker compose up

Brings up Postgres, the API, the MCP server and the web app. Fill in your Supabase project to sign in.

Read the codeCreate an account

Where an agent gets in

Identity issuing one access token two ways, a frontend and external agents such as Claude Code, Cursor, opencode or n8n, an MCP server, a FastAPI backend and PostgreSQL, with the token carried along each path
Open it full size

Your MCP server and your API run the same domain code. Publish a tool and an agent can do what that code allows, and no more.

You write the logic once, and a claim on the access token decides which door answers it.

How the security model works

What is already wired

Seven layers, and you replace any of them without unpicking the rest.

  • Product UI

    Pages rendered on the server, with one schema validating each input on both sides.

    Next.js 16, React 19, TypeScript, Tailwind CSS 4, shadcn/ui, Motion, React Hook Form, Zod, next-safe-action

  • Identity

    Credentials, sessions and agent authorization, all delegated.

    Supabase Auth (OIDC), @supabase/ssr, asymmetric JWTs verified against JWKS

  • API

    One validated HTTP door into the domain, async end to end.

    FastAPI, Pydantic v2, SQLAlchemy 2 (async), asyncpg, PyJWT

  • Agent access

    A second door into the same domain, with the user approving first.

    FastMCP, MCP over streamable HTTP, OAuth 2.1 consent

  • Data

    The tenant model, versioned and reversible.

    PostgreSQL 17, Alembic

  • Observability

    Logs you can read in dev and ship as JSON in production.

    structlog, request id and access log middleware

  • Engineering

    Nothing merges unlinted or untested, and the whole loop runs in one command.

    pytest, Vitest, Playwright, MSW, ruff, ESLint, Prettier, Docker Compose, GitHub Actions

See it work in five minutes

From a clone to an agent reading your domain, with the consent screen in between.

  1. 1

    Bring the stack up

    Postgres, the API, the MCP server and the web app, all with reload.

    docker compose up
  2. 2

    Point your agent at the door

    Any client that speaks MCP. Claude Code, opencode, Cursor and n8n all do.

    http://localhost:8001/mcp
  3. 3

    Call a tool

    The client opens a consent screen in the browser.

    whoami
  4. 4

    Approve it

    The tool answers with the profile behind the token.

# Supabase is the only service you sign up for. The rest runs in Docker.

Run it here

The same tools an agent gets, run against the server with your account. Two live in the agent's own code, and one of them stops the run to ask you; the third is the server's, so it goes through the door.

no model is called here

Connect your agent

Four ways to tell a client where the server is. The sign-in is the same in all of them: the first call opens a consent screen in the browser, and the token that comes back can only reach the tools.

Run it in your terminal. Drop --global to register the server for this project only.

opencode mcp add mcp-stack --global --url http://localhost:8001/mcp

Run /mcps, pick mcp-stack and sign in. opencode keeps the token from there on.

opencode documentation