MCP Servers

This page is for developers who connect agents to external systems such as a CMS, shop or analytics service. devkit sets up two default connections in your user scope and stores no credentials.

Scopes

Scope	Visibility
local (default)	private to you and this project
project	shared through the repository's .mcp.json
user	private, available in every project

Same-name precedence is local → project → user. Use project only for team-safe config without embedded secrets.

bash

claude mcp add <name> --scope <local|project|user> -- <command>
claude mcp list
claude mcp remove <name>

Default checks

During devkit sync, devkit checks these connections for Claude and the Codex adapter and adds a missing one through the client's own mcp add --scope user. An entry of the same name that differs from the manifest is yours: devkit leaves it alone and, on an interactive terminal, offers the remove-and-add fix at the end of the sync, defaulting to no. devkit never removes an entry on its own.

Server	Transport	Prerequisite
codegraph	stdio (codegraph serve --mcp)	codegraph installed
context7	HTTP with OAuth	authenticate once with claude mcp login context7 or /mcp

A project .mcp.json entry for context7 with its own URL, key or version pin is yours: devkit sync never rewrites project MCP files, and devkit init stops instead of touching it.

Project servers in Codex and OpenCode

Claude and Pi read the project .mcp.json directly. devkit init also adds each server missing by name to the project .codex/config.toml ([mcp_servers.*]) and opencode.json (mcp); an entry you wrote by hand is never touched, and a second run changes nothing.

A header or env value written as ${VAR} (or Bearer ${VAR}) becomes that runtime's env-var reference. A literal credential is never copied: the server is skipped for that runtime and reported as PROJECT_MCP_SKIPPED <name> <runtime> literal-credential.

devkit doctor lists each server per runtime with the env vars it needs, and the Codex session notice names servers still missing. Servers removed from .mcp.json are not removed from the mirrors.

Disable

• Per project: /mcp writes disabledMcpServers in ~/.claude.json; claude mcp remove does not clear that entry, so re-enable it in /mcp.
• Session notice: OD_SKIP_MCP_AWARENESS=1 hides the SessionStart notice about project-local servers; devkit switches lists every toggle.
• Whole session: claude --bare.

Manage OAuth connectors of claude.ai through claude.ai → Settings → Connectors or /mcp, not as hand-written project servers, and keep only current connections active: every tool schema costs session context.

Writes through MCP

An MCP write has no file diff to review, so use this loop: enumerate all targets and count them, mutate idempotently so a repeat is safe, read every value back from its source instead of trusting the success payload, and loop until zero remain or report every stuck item by name.