MCP Server — Centre d'aide

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 19 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 19 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
`codapult_plugins_migrate`	Update plugin schema and prepare DB migration

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 ai-kit 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

Verify the CLI is built: ls ../codapult-cli/dist/index.js

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

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