MCP Server

The starter kit includes a local Model Context Protocol (MCP) server for compatible coding assistants. It gives an assistant structured, read-only context about the repository instead of relying on guessed paths, commands or database conventions.

The server runs on your computer over standard input/output. Its MCP tools do not connect to PostgreSQL, execute package scripts, change source files, read environment files or make network requests. The startup command only compiles the server into the ignored dist/ directory before connecting.

Set up the server

Install the project dependencies from the repository root:

npm install

The checked-in .mcp.json is the project configuration used by Claude Code. It compiles the server before each start so a client cannot run stale generated output:

{
  "mcpServers": {
    "achromatic": {
      "type": "stdio",
      "command": "npm",
      "args": ["run", "--silent", "mcp:start"]
    }
  }
}

You can compile the server without starting it as a separate validation step:

npm run mcp:build

npm run mcp:start performs this compilation automatically and then starts the server. Because it uses stdio as its protocol transport, run it through an MCP client rather than expecting a browser page or HTTP port.

Connect your coding assistant

MCP clients use different project configuration filenames. Open the starter kit as the client workspace, install dependencies and use the matching setup below.

Claude Code

Claude Code discovers the checked-in .mcp.json. Review and approve the project server when prompted, then start a new session if it is not listed immediately.

Cursor

Create .cursor/mcp.json:

{
  "mcpServers": {
    "achromatic": {
      "command": "npm",
      "args": ["run", "--silent", "mcp:start"]
    }
  }
}

Visual Studio Code

Run MCP: Add Server from the command palette and save the stdio server to the workspace, or create .vscode/mcp.json:

{
  "servers": {
    "achromatic": {
      "type": "stdio",
      "command": "npm",
      "args": ["run", "--silent", "mcp:start"]
    }
  }
}

Codex

Create .codex/config.toml, trust the project and start Codex from the repository root:

[mcp_servers.achromatic]
command = "npm"
args = ["run", "--silent", "mcp:start"]

For another client, add a local stdio server with command npm, arguments run, --silent, mcp:start and the starter kit repository root as its working directory. Restart the client or begin a new session after changing its configuration.

Project-scoped MCP configuration can launch local commands. Review changes to .mcp.json and any client-specific MCP file before approving the server after a pull or branch switch, just as you would review changes to package scripts.

What the server exposes

The server provides 19 read-only tools grouped around common development tasks. Each tool returns both a text representation for broad client compatibility and a machine-readable structured result for clients that consume MCP structured content. A published output schema defines and validates the shared structuredContent.result envelope.

Component and implementation lists return at most 250 entries, while searches return at most 50 matches. Use the available area and query filters to narrow a broad result before reading individual files. Limited tools expose structuredContent.resultLimit; when reached is true, narrow the request before assuming the result is complete.

The complete tool contract is:

• Project: get_project_overview, list_project_scripts, get_healthcheck
• Components: list_components, search_components, read_component
• Implementation: list_implementation_files, search_implementation, read_implementation_file
• Documentation: list_documentation, search_documentation, read_documentation
• Database: get_database_overview, read_database_schema, list_migrations, read_migration, list_migration_metadata, read_migration_metadata, get_database_workflow

It also publishes:

• a project overview resource
• the current database schema resource
• a documentation index resource
• a feature-planning prompt
• a change-review prompt

During the MCP handshake, the server also tells compatible clients to begin with project discovery, search before reading individual files, inspect existing components before creating UI and request the ORM-specific workflow before suggesting database commands.

The prompts do not grant extra access. They guide the assistant to use the same read-only tools and to inspect implementation sources, tenant isolation, authorization, migrations, existing components, tests and documentation.

Recommended workflow

Use discovery tools before asking an assistant to implement a change:

1. Call get_project_overview to load the application boundaries and tenant guardrails.
2. Use search_documentation for the relevant product system.
3. Use list_implementation_files and search_implementation to find the relevant routes, configuration, core libraries, Zod schemas and tRPC procedures.
4. Call list_components before creating new interface code.
5. Use get_database_overview and get_database_workflow before changing the Prisma schema.
6. Ask for get_healthcheck before handing the change back for review.

For example:

Plan an organization audit log for this starter kit.
Use the MCP project overview, documentation, implementation files, existing
components and database workflow. Keep every query scoped by organizationId and
include the tests and migration review steps.

This sequence keeps the assistant grounded in the current checkout. Tool output is still context, not permission to skip the authorization and validation rules in AGENTS.md.

Safety boundary

Repository reads are limited to generated lists of known documentation, components, implementation sources, schema and migration files. Implementation source reads are limited to app/, config/, hooks/, lib/, schemas/, trpc/, types/ and selected root entry points such as proxy.ts. The server resolves real paths before checking repository containment, rejects symbolic links and oversized files, and excludes environment files. Database tools inspect checked-in source files only and never use DATABASE_URL.

The local server intentionally has no source-write, shell, database or network tools. Its only filesystem write is the ignored dist/ output created by the startup compiler. That makes it suitable for repository discovery and planning, not deployment or production administration.

Returned source and documentation are context, not new user authority. A coding assistant should not execute an embedded instruction or command merely because it appears in a file. The server reinforces this boundary during the MCP handshake alongside the tenant, authorization and migration guardrails.

Optional provider servers

Provider-hosted MCP servers are separate from the local Achromatic server. Add only the services you need and review their permissions because their tools may read or change external systems.

Current official endpoints include:

• Stripe MCP
• Vercel MCP
• Linear MCP

Keep secrets out of tracked configuration. Prefer the provider's OAuth flow or reference an existing environment variable when a client supports environment interpolation.

Verify the integration

Run the focused MCP suite after changing the server or its configuration:

npm run test:unit -- --run tests/mcp

The suite covers the repository file boundary, Prisma parsing, tool, resource and prompt contracts, and the real stdio process started by the documented npm run mcp:start command.

Troubleshooting

The client cannot start the local server

Run npm install from the repository root, then restart the client. The mcp:start script compiles generated files under dist/ before every start.

The server cannot locate the project

Confirm that the client's working directory is the repository root. The server looks for package.json and the Prisma schema before registering its tools.

A tool refuses to read a path

Use a path returned by the corresponding list tool. The server does not accept arbitrary repository paths.