mcp-trellis

Add authenticated AI connectors to your existing SaaS. Reuse your users, login and permissions. Trellis handles MCP + OAuth.

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.

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.

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