@terraza/terraza-mcp

Reusable MCP server toolkit for Terraza apps. Wraps the MCP SDK's OAuth 2.1 provider, HTTP transport, session management, and user resolution into a single package.

Install

npm install @terraza/terraza-mcp

Quick start

import { createTerrazzaMcpServer } from "@terraza/terraza-mcp";

await createTerrazzaMcpServer({
  name: "my-app",
  version: "0.1.0",
  resourceName: "My App MCP",
  db,  // Drizzle client that can query terraza.users
  registerTools: (server, userId) => {
    server.tool("hello", "Say hello", {}, async () => ({
      content: [{ type: "text", text: `Hello from user ${userId}!` }],
    }));
  },
  envPrefix: "MYAPP",  // checks MYAPP_MCP_TRANSPORT, MYAPP_MCP_URL, etc.
});

What it does

• OAuth 2.1 provider — In-memory, auto-approving. Handles DCR, PKCE, token rotation, and revocation. claude.ai re-auths automatically on restart.
• HTTP transport — Express app with bearer auth, per-session MCP servers, SSE streaming, health endpoint. Runs behind Caddy.
• Stdio transport — Standard MCP stdio transport for local use (Claude Desktop, Claude Code).
• User resolution — Queries terraza.users by slug to get the active user ID.
• Transport switching — Env var controls stdio vs HTTP mode. No code changes needed.

API

createTerrazzaMcpServer(config)

High-level entry point. Resolves the user, determines transport mode, starts the server.

createMcpHttpApp(options)

Lower-level. Creates a configured Express app without starting a listener. Useful for testing with supertest.

InMemoryOAuthProvider

The OAuth 2.1 provider class. Can be used standalone if you need custom HTTP wiring.

resolveUser(db, slug)

Query terraza.users by slug. Throws if not found.

terrazaUsers / terrazaSchema

Drizzle schema definitions for the shared terraza.users table.

Environment variables

| Variable | Purpose | Default | |----------|---------|---------| | {PREFIX}_MCP_TRANSPORT | Transport mode (stdio or http) | stdio | | {PREFIX}_MCP_URL | Public URL for OAuth issuer | http://localhost:{port} | | {PREFIX}_MCP_USER_SLUG | User slug for terraza.users | ken | | PORT | HTTP server port | 8002 |

All prefixed vars fall back to unprefixed versions (e.g., MCP_TRANSPORT).