MCP Server Setup

Introduction

The oss-dev MCP server gives any AI agent read-only inspection of the platform's routes, schemas, modules, events and Drizzle tables, plus write tools to scaffold and verify. It works with any MCP-compatible editor.

Zero-config setup

The fastest way to wire MCP for Claude Code. Run it right after pnpm install:

pnpm setup:mcp

It is idempotent, and does three things against the current repo:

1. Ensures .mcp.json registers the MCP server, writing the oss-dev default if missing.
2. Adds every server name to .claude/settings.json#enabledMcpjsonServers, so Claude Code trusts the server without a per-session prompt.
3. Installs the /start onboarding skill.

Restart your editor, or run /mcp, then run /start. It asks what you want to build, calls the enhance-intent tool to turn a fuzzy ask into a grounded spec, and drives the right scaffold flow.

A create:app consumer ships the same script. Run it once in the generated repo so its own agents get the toolbelt.

Server config

The server uses stdio transport, so there is no port. Add this to your editor's MCP config:

{
  "mcpServers": {
    "oss-dev": {
      "type": "stdio",
      "command": "pnpm",
      "args": ["exec", "tsx", "apps/mcp-server-dev/src/main.ts"]
    }
  }
}

| Editor | Config location | Notes | | ------------------------ | ------------------------------------------ | ------------------------- | | Claude Code | .mcp.json at repo root (already present) | Verify: claude mcp list | | Cursor | Settings > MCP, or .cursor/mcp.json | Paste the snippet above | | Windsurf | Cascade settings > MCP Servers | Paste the snippet above | | VS Code + GitHub Copilot | .vscode/mcp.json at repo root | Paste the snippet above |

Read-only inspection

Safe, no side effects.

| Tool | What it returns | | ----------------------- | --------------------------------------------------------------------- | | read-agents-md | A named section from the root or a per-module AGENTS.md | | list-modules | Every registered module with its group, tables and routes | | describe-module | Full module surface: AGENTS.md, tables, schemas and routes in one call | | list-routes | oRPC route namespaces, filterable by module | | list-extension-points | UI slots, exported events, adapter port interfaces | | query-openapi | Search the generated OpenAPI spec by keyword | | get-drizzle-schema | pgTable definitions across all modules, filterable by module | | propose-table-change | Collision-check a new table name before adding it | | schema-get | Find a Zod schema by name, with its file location | | docs-search | Full-text search across all docs and AGENTS.md files | | db-query-readonly | Run a read-only SQL query against the dev database | | enhance-intent | Turn a fuzzy "build X" ask into a classified, grounded brief | | start | Onboarding entry point - returns an interactive Q&A script | | dev:infra | Start, stop or check local docker compose infra |

Write and scaffold

These delegate to the same scripts humans use.

| Tool | What it does | | ----------------- | ----------------------------------------------- | | scaffold-module | Creates a new module skeleton and registers it | | scaffold-plugin | Creates a new overlay extension skeleton | | scaffold-route | Adds an oRPC route stub to a module | | scaffold-app | Bootstraps a new downstream consumer repo | | regen | drizzle-kit generate + OpenAPI emit + catalog | | run-verify | Runs pnpm verify |

The consumer-facing server

oss-dev is the full toolkit for working on the framework. There is a second, read-only server - @openora/mcp - published to npm for downstream consumers who want to inspect the platform surface from their own repo.

{
  "mcpServers": {
    "openora": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@openora/mcp"]
    }
  }
}

It reads docs/catalog.json, resolving it by walking up from the current directory, then falling back to the copy inside its own package.

Usage pattern for agents

1. read-agents-md         -> understand the decision tree
2. list-modules           -> see what already exists
3. describe-module        -> deep-dive before editing a specific module
4. propose-table-change   -> check for collisions before adding a table
5. scaffold-*             -> create the skeleton
6. run-verify             -> confirm nothing broke