Skip to content
Leverage AI Developer Support

MCP Setup

This repo keeps one canonical MCP source file and generates the client-specific files from it.

Source Of Truth

Section titled “Source Of Truth”
  • Canonical file: config/mcp/servers.json
  • Generated files:
    • .codex/config.toml for Codex
    • .air/mcp.json for JetBrains Air
    • .agents/mcp.json for assistant import workflows

Do not hand-edit the generated files. Update config/mcp/servers.json and regenerate.

For stdio servers that run npm packages through npx or bunx, pin the package argument to an exact version such as @scope/package@1.2.3. Mutable tags such as latest and semver ranges are rejected by the MCP config check because they can execute different package code without a repo change.

Commands

Section titled “Commands”
Terminal window
bun run mcp:generate
bun run mcp:check
  • bun run mcp:generate rewrites the generated MCP files from config/mcp/servers.json.
  • bun run mcp:check fails if the generated files are out of sync.

Codex

Section titled “Codex”

Codex supports project-scoped MCP config through .codex/config.toml in trusted projects.

  • Open the repo as a trusted Codex project.
  • Codex should read .codex/config.toml from the repo automatically.
  • Keep repo-local .codex/config.toml limited to generated MCP server config plus optional repo model defaults. Do not commit [profiles.*], profile/default_profile, [projects.*], trust settings, absolute local paths, developer names, or machine-specific approval/sandbox preferences.
  • Trust the repo through Codex’s trust prompt, or put the exact absolute path Codex reports in user-level ~/.codex/config.toml as [projects."<path>"] trust_level = "trusted".
  • Put personal Codex profiles and local path settings in user-level ~/.codex/config.toml.
  • Verify with:
Terminal window
codex mcp list

You should see the repo-managed servers there, including mastra, better_auth, nuxt, and nuxt_ui.

This workflow does not edit ~/.codex/config.toml. Global Codex MCP servers remain untouched.

Air And Assistant JSON Files

Section titled “Air And Assistant JSON Files”
  • .air/mcp.json is generated for JetBrains Air and includes the explicit transport type fields that client expects.
  • .agents/mcp.json is generated for assistant import and discovery workflows and keeps the simpler import-oriented JSON shape without transport type fields.

These files are derived outputs. If WebStorm, Air, or another tool rewrites them, regenerate from the canonical source instead of patching the generated file.

CI Failure

Section titled “CI Failure”

If generated MCP files drift from config/mcp/servers.json, CI fails with a short recovery message that tells you to:

Terminal window
bun run mcp:generate

Then commit the updated generated files.

Reserved Root File

Section titled “Reserved Root File”

The repo-root .mcp.json is reserved for JetBrains Air public preview behavior and is not part of this generation workflow.