AI Agents & IDEs — Help Center

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

Capability	File or command	Purpose
Agent guide	`AGENTS.md`	Project structure, rules, patterns, security requirements, MCP overview
Claude guide	`CLAUDE.md`	Short entrypoint for Claude Code/Claude Desktop users
Gemini guide	`GEMINI.md`	Short entrypoint for Gemini CLI/IDE users
Cursor rules	`.cursor/rules/*.mdc`	Pattern-specific rules for API routes, DB, components, adapters, plugins, server actions
Cursor MCP config	`.cursor/mcp.json`	Preconfigured MCP server connection
MCP server	`npx -y @codapult/cli@latest mcp-server`	Structured project access for compatible agents

Supported Agents

Agent or IDE	Recommended setup
Cursor	Use included `.cursor/rules` and `.cursor/mcp.json`
Claude Code	Read `CLAUDE.md`/`AGENTS.md`; connect MCP through stdio if supported by your environment
Claude Desktop	Add the Codapult MCP server to `claude_desktop_config.json`
Codex	Read `AGENTS.md`; use the MCP stdio command when MCP tools are available
Gemini CLI / Gemini Code Assist	Read `GEMINI.md`/`AGENTS.md`; use the MCP stdio command where supported
Windsurf and other MCP clients	Configure `npx -y @codapult/cli@latest mcp-server` as a stdio MCP server

MCP Server

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

29 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 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."
"Install the CRM plugin and show what files changed."
"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.