mcp-trellis

Plug your existing SaaS's users, login and permissions into MCP with OAuth 2.1 — so Claude, ChatGPT and other AI clients can act on your app as that user, with one npm install and no separate identity provider.

Existing SaaS
users + login + data
       ↓
    mcp-trellis
       ↓
Claude / ChatGPT / Gemini

Demo

npm install mcp-trellis

Related MCP server: Remote MCP Server on Cloudflare

The 30-second example

import { createMcpApp, signedTokenAuth } from "mcp-trellis";
import { session, projectsForUser, codeStore } from "./your-app.js";

export const mcp = createMcpApp<{ userId: string }>({
  serverInfo: { name: "my-saas", version: "1.0.0" },
  auth: signedTokenAuth({
    secret: process.env.MCP_SECRET!,
    resolveUser: (req) => session(req),
    loginUrl: (_r, n) => `/login?next=${encodeURIComponent(n)}`,
    codeStore,
  }),
  context: (_r, p) => ({ userId: p!.id }),
  tools: [{ name: "list_my_projects", description: "List projects",
    inputSchema: { type: "object", properties: {} }, scope: "mcp",
    handler: async ({ userId }) => JSON.stringify(await projectsForUser(userId)) }],
});

codeStore must be a shared single-use store (Redis/KV — see examples/stores.ts). Advanced ports (mintAccessToken, verifyToken, refresh, revoke) remain available when you outgrow the helper. Node ≥20.

View the complete SaaS demo — working login, consent, two users with different projects.

Also listed on the Official MCP Registry as Project desk (reference remote server; not the SDK) — see examples/project-desk.

Use cases

• Let Claude or ChatGPT read and act on a signed-in user's own data (their projects, tickets, invoices) in your product — no shared service account, no "god token".

• Add a remote MCP connector to a Next.js, Express, or Cloudflare Workers app that already has sessions and a user table, without introducing a separate identity provider.

• Give an AI agent tools that are scoped by the same permissions and multi-tenant boundaries your app already enforces (see Multi-tenant).

• Expose a handful of user-scoped tools from an existing codebase in under 15 lines, instead of standing up an MCP server and an OAuth stack as two separate projects.

When should I use this?

• Your TypeScript app already has login and user data, and you want to expose user-scoped tools through remote MCP.

• You want the MCP handler and OAuth authorization endpoints in one package, with zero runtime dependencies.

• You want to reuse your runtime and existing storage. The library does not require a new database; production deployments still need appropriate replay, token and session storage.

When should I not use this?

• You need a managed identity provider, a user database, or a login system built for you.

• You already have an MCP server and authorization server that meet your needs.

• You need protocol features or client combinations absent from the verified support table.

• You only need a local stdio tool with no remote authorization flow.

Why trellis vs the official SDK / fastmcp / mcp-framework

The official TypeScript SDK, fastmcp and mcp-framework are general-purpose tools for building a new MCP server. mcp-trellis is narrower on purpose: it wires an existing SaaS's users and login into MCP as a self-hosted OAuth 2.1 authorization server. Checked against each project's README and package.json on 2026-10-29, and the dependency counts against the npm registry on 2026-11-02 — re-verify before relying on it, all four move fast:

If you're building a brand-new MCP server, any of the three above is a better fit — they have the ecosystem, docs, and tooling for exactly that. mcp-trellis solves a narrower problem: you already have a SaaS with users and permissions, and you want Claude/ChatGPT to act on it as a specific signed-in user without standing up a separate identity provider. For a feature matrix against identity-product compositions (xmcp + Scalekit, WorkOS, Descope, Auth0, …), see docs/ROADMAP.md.

Run a real tool

The Project desk demo is the canonical example (examples/project-desk implementation): app login → OAuth consent → access token → list_my_projects. Alice sees her two projects; Bob sees his own. It uses fictional data and an independent app session.

Live Claude / ChatGPT recordings are still pending. Automated OAuth tests are not evidence that a current vendor client has connected successfully.

Clients and compatibility

Protocol versions implemented: 2024-11-05, 2025-03-26, 2025-06-18; default 2025-06-18. See test evidence and verification checklist, client configuration and troubleshooting.

Integrate with your app

Prefer signedTokenAuth for a one-secret start. For refresh, revoke, or your own JWT/JWKS, implement resolveUser, loginUrl, mintAccessToken and verifyToken yourself. Mint tokens for the requested MCP resource and return their verified audience; the library rejects an audience mismatch before executing tools. A logged-in user still sees an OAuth consent screen. Your data layer must enforce ownership and tenant permissions. Browser callers that send an Origin header need allowedRequestOrigins (fail-closed by default) — see security.md.

SaaS demo · Next.js starter · Host recipes · Security · npm

How it compares

mcp-trellis is the vendor-neutral embedded BYO-auth path: MCP handler and self-hosted OAuth AS in one npm install. Contrast composition stacks such as xmcp + Scalekit (or WorkOS / Descope connectors) that split the MCP runtime and the identity product across 2–3 packages. Full comparison table: docs/ROADMAP.md.

Architecture

createMcpApp wires MCP and OAuth and routes between them:

Host recipes, ports, tools, and multi-tenant: docs/guide.md.

Docs

Canonical example: examples/project-desk (local docs). Recipes: examples/.

Contributing

PRs welcome — see CONTRIBUTING.md.

npm test
npm run build
npm run typecheck

License

MIT