MCP Protocol

import { Aside } from ‘@astrojs/starlight/components’;

What is MCP?

The Model Context Protocol (MCP) is an open specification for connecting AI models to external data sources and tools. Published by Anthropic under the MIT License, MCP is a standardized way for AI agents to discover and call tools provided by external servers.

MCP solves a coordination problem: every AI coding agent previously had to invent its own plugin system, and every tool had to be reimplemented for each agent. With MCP, a tool that speaks the protocol works with any agent that speaks the protocol.

Forge implements the MCP server side of the protocol. AI agents (Claude Code, Cursor, Windsurf, Zed, Continue, and others) implement the MCP client side.

Ironpine Labs is not affiliated with or endorsed by Anthropic. "Model Context Protocol" and "MCP" are used in their descriptive sense — Forge implements this open specification.

How Forge uses MCP

Transport

Forge uses the stdio transport: the MCP client (your AI agent) launches forge serve as a subprocess and communicates over stdin/stdout. This is the most common MCP transport and is universally supported.

{
  "mcpServers": {
    "forge": {
      "command": "forge",
      "args": ["serve", "."],
      "env": {}
    }
  }
}

No HTTP server. No ports to configure. No networking between agent and Forge. The agent and Forge are the same process group, communicating through pipes.

Protocol messages

All messages are JSON-RPC 2.0 over the stdio pipe. The key exchanges:

1. initialize — Client announces capabilities. Forge responds with its server info and injects behavioral instructions into the system prompt.
2. tools/list — Client requests the full tool manifest. Forge returns all 21 tools with their JSON Schema input definitions and descriptions.
3. tools/call — Client calls a specific tool with arguments. Forge runs the query and returns the result.

Server instructions

The most important thing Forge does at initialize time is inject a block of behavioral instructions into the agent’s context. These instructions:

• Define the correct order of operations (forge_prepare before edit, forge_validate after)
• Explain when to use workflow tools vs detailed tools
• Teach the agent how to interpret GO/CAUTION/STOP assessments
• Document the tool categories and when to reach for each

This is why Forge’s behavior in properly configured agents is automatic. The agent learns the intended workflow from Forge itself at the start of every session, without the user needing to write a system prompt or custom instructions.

The 21 tools

Forge’s tools are organized into six categories. The three workflow tools handle the most common AI-agent use cases. The 18 detailed tools are for targeted analysis.

Workflow tools (start here)

These three tools are the highest-leverage entry points. Each bundles multiple detailed tool calls into a single result:

Tool	When to use	Returns
forge_prepare	Before any file modification	Dependents, imports, health findings, coverage, git activity, GO/CAUTION/STOP
forge_validate	After file modifications complete	Health delta (new findings introduced vs fixed), import verification
forge_understand	When encountering unfamiliar code	Full structural analysis: symbols, callers, dependencies, test coverage, recent history

Search tools

Tool	When to use	Returns
forge_search	Find code by concept or keyword	Ranked file+snippet results, camelCase-aware
forge_pattern_search	Find structural code patterns	All locations matching an ast-grep pattern
forge_search_symbols	Find symbols by name	All functions/classes/types matching a name query

Graph tools

Tool	When to use	Returns
forge_trace_imports	What does this file depend on?	Outbound import edges from a file
forge_trace_dependents	Who depends on this file?	Inbound import edges pointing to a file
forge_check_wiring	Is this module connected?	Reachability from any entry point in the graph
forge_find_cycles	Are there circular deps?	Circular dependency chains (if any)
forge_dependency_graph	Full subgraph visualization	DOT-format or JSON dependency graph for a path

Health tools

Tool	When to use	Returns
forge_health_check	Run all health checks	P0/P1/P2/info findings across the repo

AST tools

Tool	When to use	Returns
forge_parse_file	Raw symbol list for a file	Every symbol in a file with type, line, exported status
forge_extract_symbol	Get the full source of a symbol	Source code + context for a named function/class/type

Git tools

Tool	When to use	Returns
forge_git_history	Recent commits for a file	Last N commits: hash, author, date, message
forge_git_blame	Per-line authorship	Blame data for a line range

Ingest tools

Tool	When to use	Returns
forge_ingest_scip	Upgrade to compiler-resolved edges	Confirmation + edge count before/after
forge_coverage	Ingest test coverage	Coverage stored; per-file % queryable by workflow tools

Index tools

Tool	When to use	Returns
forge_index_status	Check index health	File counts, stale files, last index time, which layers are ready
forge_reindex	Trigger incremental re-index	Re-index result (files processed, duration)

Tool design philosophy

Workflow tools wrap detail tools

forge_prepare is not magic — it calls forge_trace_dependents, forge_trace_imports, forge_health_check, forge_git_history, and optionally forge_coverage under the hood, then synthesizes the results into a single actionable summary.

This composability is intentional. You can call the detail tools directly when you need targeted information. Use workflow tools when you want a complete picture.

Structured JSON output

All tools return structured JSON. This makes results machine-readable and allows the agent to reason about them programmatically — counting dependents, sorting findings by severity, comparing before/after states.

Tool descriptions as documentation

Each tool’s MCP description is written to be read by AI agents, not just humans. The descriptions explain not just what the tool does but when to use it, what inputs to provide, and how to interpret the output. This is part of why Forge agents need minimal prompting — the tools are self-documenting.

Which agents work with Forge?

Any agent that supports MCP stdio transport can use Forge. Tested combinations:

Agent	MCP support	Notes
Claude Code	Full	Primary test target. Server instructions fully supported.
Cursor	Full	Config via cursor_mcp_config.json in project root
Windsurf	Full	Config via workspace settings
Zed	Full	Config via settings.json context server block
Continue (VS Code)	Full	Config via config.json
Codex CLI	Full	--mcp-config flag or CODEX_MCP_CONFIG env var

For per-agent setup guides, see the How-To section.