MCP Server

What Is MCP

The Model Context Protocol (MCP) server ships as part of @codapult/cli. It gives AI coding assistants — Cursor, Claude Desktop, Windsurf, Codex, and others — structured access to your project's schema, environment, plugins, deployment status, and more without copy-pasting context.

The server exposes 18 tools, 6 resources, and 2 prompt templates over a JSON-RPC stdio transport.

Setup

Prerequisites

Make sure the CLI is built before configuring your editor:

cd ../codapult-cli && pnpm install && npx tsc

Cursor

A .cursor/mcp.json is already included in the project root:

{
  "mcpServers": {
    "codapult": {
      "command": "node",
      "args": ["../codapult-cli/dist/index.js", "mcp-server"],
      "cwd": "."
    }
  }
}

Open Settings → MCP and verify the codapult server is listed and active.

Claude Desktop

Add the following to your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "codapult": {
      "command": "node",
      "args": ["/absolute/path/to/codapult-cli/dist/index.js", "mcp-server"]
    }
  }
}

Other Editors

Any MCP-compatible editor can connect. Point it to the stdio transport:

node /path/to/codapult-cli/dist/index.js mcp-server

Available Tools

The MCP server provides 18 tools organized into 6 categories.

Project Introspection

| Tool | Description | | ------------------------- | --------------------------------------- | | codapult_project_status | Adapters, plugins, features, git status | | codapult_project_config | Read src/config/app.ts | | codapult_run_checks | Run lint, typecheck, and/or tests | | codapult_doctor | Health check: files, TypeScript, env |

Database

| Tool | Description | | ---------------------------- | --------------------------------------- | | codapult_db_get_tables | List all tables with column counts | | codapult_db_get_table_info | Columns, types, constraints for a table | | codapult_db_status | Provider, table count, migrations |

Environment

| Tool | Description | | --------------------- | ---------------------------------------------- | | codapult_env_schema | All vars from .env.example with descriptions | | codapult_env_read | Current .env.local values + validation | | codapult_env_update | Set a single env variable |

Plugins

| Tool | Description | | ------------------------- | ----------------------------------------------- | | codapult_plugins_list | List installed plugins | | codapult_plugins_add | Install a plugin (patches schema, config, etc.) | | codapult_plugins_remove | Uninstall a plugin |

Code Generation

| Tool | Description | | -------------------------- | ------------------------------------------------ | | codapult_generate_page | Dashboard page (server component, auth, Card UI) | | codapult_generate_api | API route (auth + rate limit + Zod) | | codapult_generate_action | Server action (auth + Zod) | | codapult_generate_plugin | Full plugin scaffold |

Deployment

| Tool | Description | | ------------------------ | --------------------------------------------- | | codapult_deploy_status | Dockerfile, Helm, Terraform, Pulumi readiness |

Resources

Resources are read-only data that AI assistants can automatically load as context:

| Resource | URI | Description | | ---------------------- | ------------------------------ | --------------------------------------- | | codapult_schema | codapult://schema | Full Drizzle ORM schema (all tables) | | codapult_app_config | codapult://config/app | App config (brand, features, AI, auth) | | codapult_agents_md | codapult://agents | AGENTS.md (project conventions) | | codapult_env_example | codapult://env-example | .env.example (all env vars with docs) | | codapult_validation | codapult://validation | All Zod validation schemas | | codapult_navigation | codapult://config/navigation | Dashboard and admin sidebar items |

Resources are automatically available in clients that support MCP resources (e.g. Claude Desktop).

Prompt Templates

The MCP server provides context-aware prompt templates that auto-inject your current project schema and configuration:

| Template | Purpose | | ------------------------ | ---------------------------------------------------------------------------- | | codapult_code_review | Review code against Codapult conventions (API pattern, TypeScript, adapters) | | codapult_schema_design | Design a Drizzle ORM table following Codapult conventions |

Usage Examples

Once connected, your AI assistant automatically has access to all tools. Try asking:

• "What adapters is the project using?"
• "List all database tables"
• "Add the video-player plugin"
• "Generate a new dashboard page called analytics"
• "Check deployment readiness"
• "What environment variables am I missing?"
• "Run the linter and fix any errors"

The AI assistant calls the appropriate MCP tool and gets structured data back — no manual context needed.

Architecture

┌─────────────┐    JSON-RPC / stdio    ┌──────────────────┐
│  AI Editor   │ ◀────────────────────▶ │  Codapult MCP    │
│  (Cursor,    │                        │  Server           │
│   Claude)    │                        │  (@codapult/cli)  │
└─────────────┘                        └──────────────────┘
                                                │
                                                ▼
                                       ┌──────────────────┐
                                       │  Codapult         │
                                       │  Project Files    │
                                       │  (schema, env,    │
                                       │   config, etc.)   │
                                       └──────────────────┘

The MCP server reads project files directly and executes CLI commands. No database connection or API keys are needed for basic operation.

Troubleshooting

Server not showing up

1. Verify the CLI is built: ls ../codapult-cli/dist/index.js
2. Test manually:

   echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"0.1.0"}}}' | node ../codapult-cli/dist/index.js mcp-server
   

3. Check that .cursor/mcp.json paths are correct

Tools not working

The MCP server must be run from the Codapult project directory (or a child directory). It traverses up to find package.json with name: "codapult".

After updating @codapult/cli

Rebuild the CLI so the MCP server picks up changes:

cd ../codapult-cli && npx tsc