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, Gemini, and others - structured access to your project's schema, environment, plugins, deployment status, and more without copy-pasting context.

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

For the broader agent setup, see AI Agents & IDEs.

Setup

Prerequisites

The published CLI is downloaded automatically through npm when the MCP server starts. A purchased project does not contain or build the CLI source, and no global CLI installation is required. The npx invocation uses npm's local cache; it does not install a permanent global codapult command. For manual CLI commands, use npx @codapult/cli <command>; without a version suffix, npx resolves the current published package. The explicit @latest below is intentional for MCP server startup and CI, where the project should follow the latest published MCP contract. To select a specific published MCP version, run npx @codapult/cli mcp update <version> and reload the MCP connection.

Cursor

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

{
  "mcpServers": {
    "codapult": {
      "command": "npx",
      "args": ["-y", "@codapult/cli@latest", "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": "npx",
      "args": ["-y", "@codapult/cli@latest", "mcp-server"]
    }
  }
}

Other Editors

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

npx -y @codapult/cli@latest mcp-server

When the client supports a working directory, set it to your Codapult app root so the server can discover package.json, src/lib/db/schema.ts, .env.example, and AGENTS.md.

Available Tools

The MCP server provides project context, checks, environment management, database operations, plugin management, code generation, and deployment readiness tools. Mutating tools support dry_run where applicable, so an agent can preview changes before applying them.

The CLI and MCP use the same health engine and structured report. npx @codapult/cli doctor checks the project itself, including parity between src/lib/db/schema.ts and src/lib/db/schema-pg.ts; npx @codapult/cli mcp doctor (and the codapult_doctor MCP tool) additionally verifies that .cursor/mcp.json points to a valid @codapult/cli server.

The health report also performs an environment-schema drift check. It parses src/config/env-schema.ts with the TypeScript AST and compares its keys with the CLI's reviewed mirror contract. If a variable was added or removed, the report lists schemaOnly and mirrorOnly keys so the MCP semantics can be updated deliberately.

For CI, run npx @codapult/cli@latest mcp contract-check. It exits with code 1 when the host env-schema.ts and the CLI compatibility contract differ. Review the reported keys and update the shared environment semantics in the CLI before publishing the next CLI version.

The same command can be added to the template repository's CI after dependencies are installed:

- name: Check MCP environment contract
  run: pnpm dlx @codapult/cli@latest mcp contract-check

Project Introspection

Database

Environment

codapult_env_check and codapult_env_read report the effective configuration, not only raw values. This includes APP_MODE, selected providers, auth methods, OAuth providers, and feature flags. Conditional requirements such as database, payment, storage, jobs, notifications, and support credentials are checked against the active providers.

codapult_env_read masks sensitive values by default. Passing show_secrets: true returns a security warning because plain-text values may enter the AI context.

codapult_db_migration_diff runs Drizzle in a temporary migration directory and returns the pending SQL without modifying the project's schema or migration files. It compares the source schema with local migration history; it does not inspect or change the live database.

Database table inspection also uses the TypeScript AST rather than line-based regular expressions. Formatting, multiline declarations, chained Drizzle column modifiers, PostgreSQL types, and nested callback expressions therefore remain inspectable.

codapult_db_live_diff performs a separate read-only drift check against the configured Turso or PostgreSQL database. It issues metadata SELECT/PRAGMA queries only: it never executes migrations, push, or DDL. It returns table/column/type differences and never includes connection credentials in its result.

codapult_db_schema_diff checks parity between src/lib/db/schema.ts and src/lib/db/schema-pg.ts. Missing tables or columns are failures; provider-specific type representations are normalized where possible, and incompatible types are warnings. The CLI equivalent is npx @codapult/cli db schema-diff.

Service tables such as __drizzle_migrations are ignored. Application tables that exist in the live database but no longer exist in the source schema are reported, which is useful for spotting legacy tables before cleanup.

Plugin schemas follow the CLI installation lifecycle. plugins add copies the plugin's declared SQLite and PostgreSQL tables into the corresponding host schema files, and plugins migrate updates those marked blocks. Therefore live-diff intentionally checks only the active host schema; it does not scan sibling plugin repositories or plugin source files. If a plugin table remains in the database after the plugin was removed, or its schema block was not installed, it is reported as missing_in_schema. Review it before cleanup or reinstall/integrate the plugin first.

Plugins

Code Generation

Deployment

Resources

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

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

Updating MCP

The generated configuration starts with @latest. For a reproducible setup, pin the MCP version from the project root:

npx @codapult/cli mcp update

You can select a specific version with npx @codapult/cli mcp update 0.15.3. Use --dry-run to preview the change without writing .cursor/mcp.json. Reload or restart the MCP connection in the editor after updating.

Prompt Templates

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

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"
• "Configure the AI gateway and enable RAG"
• "Generate a new dashboard page called analytics"
• "Check deployment readiness"
• "What environment variables am I missing?"
• "Run the linter and fix any errors"
• "Install the CRM plugin and prepare the migration"
• "Generate a protected API route for saved reports"
• "Check Docker, Helm, Terraform, and Pulumi deployment readiness"

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 Server  │
│  (Cursor, 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 that the CLI can be resolved: npx -y @codapult/cli --version
2. Test manually:

   echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"0.1.0"}}}' | npx -y @codapult/cli@latest mcp-server

3. Check that .cursor/mcp.json exists and that the editor's working directory is the Codapult project root

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

Update the project MCP configuration and reload the editor connection:

npx @codapult/cli mcp update
npx @codapult/cli mcp doctor

The CLI package is maintained and published by Codapult. Buyers normally do not edit, build, or install codapult-cli from source.