MCP tool surface
How the MCP server exposes Echo to any agent — one stable tool set regardless of connected sources.
Echo's MCP server exposes the faceted contract as a set of tools any MCP-compatible agent can call. The tool set is stable: the same tools work regardless of which sources are connected, and adding a source never adds a tool.
The tool set
| Tool | Maps to | Description |
|---|---|---|
echo_discover | Discover | List sources and their sync state for a project |
echo_search | Search | Search across sources with a natural-language query |
echo_fetch | Fetch | Resolve a ref to its full content and graph neighborhood |
echo_activity | Activity | Get time-ordered events from sources that carry a clock |
Authentication
The MCP server authenticates using the same two paths as the HTTP API: a service key (X-API-Key) or a user JWT. Configure the key in your MCP client's server configuration.
{
"mcpServers": {
"echo": {
"url": "https://your-echo-instance.example.com/mcp",
"headers": {
"X-API-Key": "your-service-key"
}
}
}
}Tool arguments
echo_discover
{
"project_id": "proj_abc123"
}Returns the same shape as the Discover HTTP response.
echo_search
{
"project_id": "proj_abc123",
"query": "where do we validate session tokens?",
"sources": ["code", "work_items"],
"top_k": 10
}echo_fetch
{
"project_id": "proj_abc123",
"ref": "code:github:acme/api:main:src/auth/verify.ts:verifySession"
}echo_activity
{
"project_id": "proj_abc123",
"sources": ["commits", "work_items"],
"since": "2025-11-25T00:00:00Z",
"limit": 25
}Why the tool set is stable
Because every source flows through the same four contract operations, the MCP tools mirror those operations one-to-one. A new source appears in echo_discover, its entities appear in echo_search, and its refs resolve in echo_fetch. No tool definitions change.