AI Agents & IDEs

Codapult is designed to work well with AI coding agents and AI-native IDEs. The repository includes agent instructions, Cursor rules, and an MCP server that exposes project-aware tools, resources, and prompt templates.

What Is Included

Supported Agents

MCP Server

The MCP server ships with @codapult/cli and exposes:

• 29 Codapult template tools for project context, project status, database operations (including read-only live schema diff), env validation, plugin management, code generation, checks, and deployment readiness.
• 8 resources: schema, app config, env config, AGENTS.md, .env.example, validation schemas, navigation config, and all non-test src/config files.
• 2 prompt templates for Codapult code review and schema design.

The CLI also contributes 14 tools, 6 resources, and 2 prompt templates for architecture discovery, policy proposals, verification, review packets, run history, and time-bounded waivers through its integrated Guard capabilities.

The published CLI is downloaded automatically through npx; no global CLI installation, codapult-cli source repository, or local CLI build is required. To update the published MCP server version, run npx @codapult/cli mcp update and reload the editor connection.

Start the server:

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

Pin or update the MCP version from the project root:

npx @codapult/cli mcp update

Run the same project health checks used by MCP:

npx @codapult/cli mcp doctor

Full reference: MCP Server.

Cursor

The project includes:

{
  "mcpServers": {
    "codapult": {
      "command": "npx",
      "args": ["-y", "@codapult/cli@latest", "mcp-server"],
      "cwd": "."
    }
  }
}

Open Cursor settings and verify the codapult MCP server is active.

Claude Desktop

Add a stdio server entry:

{
  "mcpServers": {
    "codapult": {
      "command": "npx",
      "args": ["-y", "@codapult/cli@latest", "mcp-server"],
      "cwd": "/absolute/path/to/codapult"
    }
  }
}

Agent-Safe Workflows

Ask agents to use Codapult MCP tools instead of guessing:

• "Run Codapult doctor and tell me what is misconfigured."
• "List all database tables and propose a schema for saved reports."
• "Generate a protected dashboard page for invoices."
• "Inspect the project's installed capabilities and show what files and configuration they use."
• "Check deployment readiness for Docker and Terraform."

The MCP server reads project files directly and returns structured results, which reduces stale context and copy-paste errors.

Guardrails for Agents

When prompting an agent, include these constraints:

• Follow AGENTS.md and .cursor/rules.
• Use @/ imports and existing UI components.
• Server components by default; add 'use client' only when browser state or effects are needed.
• API route pattern: auth, rate limit, Zod validation, business logic, JSON response.
• Server actions must validate input, check permissions, and revalidate affected paths.
• Never expose secrets through NEXT_PUBLIC_ variables.
• Keep modules removable and respect codapult:prune markers.