@arcadeai/arcade-mcp

TypeScript MCP framework with secret injection, OAuth auth providers, multi-user support, worker routes, and middleware. Wraps the official @modelcontextprotocol/sdk — never forks or patches it.

Quick Start

bun add @arcadeai/arcade-mcp

import { MCPApp } from "@arcadeai/arcade-mcp";
import { z } from "zod";

const app = new MCPApp({
  name: "MyServer",
  version: "1.0.0",
  instructions: "A helpful tool server",
});

app.tool(
  "greet",
  {
    description: "Greet someone by name",
    parameters: z.object({
      name: z.string().describe("Name to greet"),
    }),
  },
  async (args) => `Hello, ${args.name}!`,
);

app.run(); // stdio by default

Run it:

bun run server.ts

Or over HTTP:

app.run({ transport: "http", port: 8000 });

CLI Auto-Discovery

Run an MCP server without writing a server file. The CLI auto-discovers tool modules in the current directory:

npx @arcadeai/arcade-mcp          # auto-discover tools, run stdio
npx @arcadeai/arcade-mcp --http   # auto-discover tools, run HTTP

Tool modules are discovered from:

• *.tools.ts / *.tools.js files (e.g., math.tools.ts)
• Any file inside a tools/ directory (e.g., tools/greet.ts)

Each file should export tool definitions:

// tools/greet.ts
import { z } from "zod";

export const greetTools = {
  greet: {
    options: {
      description: "Greet someone",
      parameters: z.object({ name: z.string() }),
    },
    handler: async (args) => `Hello, ${args.name}!`,
  },
};

CLI options:

Node.js + TypeScript: Use npx tsx arcade-mcp or Bun to import .ts tool files directly.

Dev Mode (Auto-Reload)

Watch source files and automatically restart the server on changes:

npx @arcadeai/arcade-mcp --http --dev

Or programmatically:

app.run({ transport: "http", dev: true });

When a .ts, .js, .mts, or .mjs file changes, the server stops, re-imports tool modules with fresh copies, and restarts. Files in node_modules/, dist/, and hidden directories are ignored.

Note: Dev mode only works with HTTP transport. Stdio sessions cannot be restarted.

You can also enable dev mode via the ARCADE_SERVER_RELOAD=1 environment variable.

Features

• Builder API — app.tool(name, options, handler) with method chaining
• Secret injection — env vars auto-captured and injected into tool context
• OAuth auth providers — 21 providers: GitHub, Google, Slack, Microsoft, Linear, Notion, etc.
• Context object — namespaced facades for logging, progress, sampling, resources, tools, UI
• Middleware — composable onion-model middleware with method-specific hooks
• Multi-user HTTP auth — JWT Bearer token validation via JWKS
• Worker routes — /worker/tools, /worker/tools/invoke, /worker/health
• Error hierarchy — structured errors with retry support, upstream error mapping
• Prompts — app.prompt(name, options, handler) with argument validation and runtime management
• Resources — app.resource(uri, options, handler) with MIME types and runtime management
• Dev mode — auto-reload on file changes with --dev flag (HTTP only)
• Resumable streams — optional event store for HTTP stream resumability via Last-Event-ID
• Evals — evaluate LLM tool-calling accuracy with critics, rubrics, and Hungarian-optimal matching
• Dual transport — stdio and HTTP (Elysia + StreamableHTTP)
• Runtime compatible — Bun and Node.js (no Bun.* APIs in library code)

Tool Opt

... View full README on GitHub