MCP is the open protocol that lets coding agents reach external systems - Linear, Sentry, Notion, your database, custom internal services - through a single standard rather than a custom integration per vendor. Claude Code's MCP support is one of the main reasons teams pick it. This page covers how MCP works in Claude Code, the common gotchas, and how cto CLI handles the same protocol with a different config model.
TL;DR. Claude Code configures MCP via .claude/mcp.json (per project) or ~/.config/claude-code/mcp.json (user). cto CLI uses opencode's native MCP support - same protocol, configure servers in opencode's standard MCP config format (stdio or streamable HTTP). Both clients call the same MCP protocol; the difference is config UX.
MCP, in one paragraph
The Model Context Protocol (MCP) is an open standard for connecting AI agents to external tools and data sources. An MCP server exposes capabilities - file reads, ticket creation, database queries; any MCP-compatible client (Claude Code, cto CLI, Cursor, Claude Desktop, Codex CLI, Gemini CLI, GitHub Copilot CLI) can call them. MCP was launched by Anthropic in late 2024 and reached cross-vendor support across OpenAI, Google, and most major IDEs by mid-2026. As of 2026 there are 9,400+ public MCP servers.
How MCP works in Claude Code
Config file location
Project-level config lives in .claude/mcp.json at your repo root. User-level config is in ~/.config/claude-code/mcp.json (or ~/Library/Application Support/Claude/mcp.json on macOS).
Adding a server
claude mcp add github
claude mcp add linear --env LINEAR_API_KEY=...
Or edit the JSON directly:
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "..." }
}
}
}
Restart the session and the server's tools appear alongside built-in tools.
Popular MCP servers used with Claude Code
| Server | What it does |
|---|---|
github | PR/issue management beyond git |
linear | Read/write Linear tickets |
sentry | Pull error groups, traces |
notion | Read/write Notion pages |
postgres | Read-only SQL queries |
puppeteer | Browser automation for testing |
fetch | Read web pages as markdown |
Transports
MCP servers come in two flavors:
- stdio - run as a local subprocess started by your config. Fast, secure, requires local install per user.
- streamable HTTP - run remotely at a URL. Auth via OAuth or bearer token. Useful for vendor-hosted MCP.
Claude Code supports both.
Common gotchas
- Server fails to start silently. Run
claude mcp(no args) to list configured servers and their state. - Tools not appearing. Restart the session - tool discovery is at session start, not config reload.
- Tokens in env, not committed. Use user-level config or OS keychain, not
.claude/mcp.jsonif that's checked in. - HTTP server 401. Bearer expired or wrong header. Logs at
~/.cache/claude-code/logs/.
How MCP works in cto CLI
cto CLI ships as an opencode plugin + provider, and MCP support is opencode-native - same protocol, same standard config UX as vanilla opencode. The cto wrapper doesn't add or modify MCP behavior; whatever MCP server you'd wire into opencode, you wire into cto CLI the same way.
Adding a server
Use opencode's standard MCP config. Add stdio or streamable HTTP servers to opencode's config file with your auth, restart the session, and the agent picks them up alongside the built-in tools. The full list of MCP servers you can call is whatever's in the broader MCP ecosystem - 9,400+ public servers as of 2026, plus any custom server you build yourself.
The cto.new gateway sits between the CLI and the LLM providers (so you don't bring API keys), but it doesn't sit between the CLI and your MCP servers - your MCP server calls go out from the CLI process directly, same as vanilla opencode.
MCP in other CLIs
Cursor CLI
Native MCP. Config in .cursor/config.json (per project) or ~/.cursor/mcp.json (global). Same servers work; config format is slightly different from Claude Code's.
GitHub Copilot CLI
Native MCP since March 2026, shared with the VS Code extension. Config in ~/.copilot/mcp.json.
Codex CLI
Native MCP client. Config in ~/.codex/config.toml; per-project scope via .codex/config.toml for trusted projects. Codex can also run itself as an MCP server.
Gemini CLI
Native MCP. Config in ~/.gemini/settings.json.
Aider
No native MCP client. Community projects like aider-mcp-server expose Aider's tools to MCP clients - the inverse direction.
What MCP unlocks (real examples)
Three patterns in production:
1. PR review with Sentry context
Agent reads the PR diff, calls the Sentry MCP server to check whether any changed code paths have active error groups, includes that context in the review.
2. Ticket-to-PR
Lead agent reads a Linear ticket (Linear MCP), researches the codebase, drafts the implementation, opens a PR linking back to the ticket.
3. Deploy-failure triage
When a deploy fails, an agent reads the failure logs (CI MCP), checks recent commits (GitHub MCP), creates a triage thread (Slack MCP), posts a hypothesis with file references.
FAQ
How do I install an MCP server in Claude Code?
claude mcp add <name> or edit ~/.claude/mcp.json manually. Restart the session. Run claude mcp to list configured servers.
How do I install an MCP server in cto CLI?
Use opencode's standard MCP config - cto CLI is an opencode plugin + provider, so the MCP UX is whatever you'd do in vanilla opencode. Add stdio or streamable HTTP server entries; restart the session.
Are MCP servers free?
The protocol and most public servers are free + open source. Some hosted MCP servers (Ahrefs, Linear, Sentry hosted) require API access at vendor pricing.
Can I write my own MCP server?
Yes - the MCP SDKs (TypeScript, Python, others) make a basic server ~100 lines.
Is MCP supported by ChatGPT?
Yes - OpenAI added MCP support to ChatGPT and Codex CLI in March 2025. Most major AI products now support it.
Should I run MCP servers locally or use hosted ones?
Local (stdio) servers are faster and don't require network round-trips, but each user must install them. Hosted (streamable HTTP) are easier to share across a team but add auth complexity. For dev workflows, local; for shared team integrations, hosted.
What's different about cto CLI's MCP UX vs Claude Code?
Not much functionally - both use the open MCP protocol. cto CLI inherits opencode's MCP config format (so your config travels with opencode, not with cto specifically). Claude Code's per-project .claude/mcp.json is convenient for checking config into your repo; opencode's pattern is different but equivalent in capability.