MCP Servers

UGENT connects to Model Context Protocol (MCP) servers to extend the agent with external tools, search engines, code analyzers, and more.

Enabling MCP

[mcp]
auto_connect = true

When auto_connect is enabled, UGENT connects to all configured MCP servers on startup. Tools are auto-discovered via the list_tools() protocol method.

Transport Types

HTTP (Streamable HTTP)

[mcp.services.exa]
enabled = true
max_inflight_calls = 1

[mcp.services.exa.transport]
type = "http"
url = "https://mcp.exa.ai/mcp?exaApiKey=YOUR_KEY"

[mcp.services.exa.transport.options]
allow_stateless = true
connect_timeout_secs = 30
request_timeout_secs = 60
reinit_on_expired_session = true

stdio (Local Process)

[mcp.services.context-mcp]
enabled = true
max_inflight_calls = 1

[mcp.services.context-mcp.transport]
type = "stdio"
command = "ugent-context-mcp"
args = ["--server-url", "http://localhost:9002/rpc", "--token", "your-token"]

Unix Socket (Unix only)

[mcp.services.daemon-mcp]
enabled = true

[mcp.services.daemon-mcp.transport]
type = "unix_socket"
socket_path = "/tmp/mcp.sock"
uri = "http://localhost/mcp"

ugent-context-mcp

The context intelligence MCP server provides semantic code search, knowledge graph traversal, and graph statistics. It connects to the UGENT context engine over HTTP.

Setup

1. Start the context engine server:

ugent-context-engine

2. Configure in ugent.toml:

[mcp.services.ugent-context-mcp]
enabled = true
max_inflight_calls = 1

[mcp.services.ugent-context-mcp.transport]
type = "stdio"
command = "ugent-context-mcp"
args = ["--server-url", "http://localhost:9002/rpc", "--token", "dev-token"]

Available Tools

Tool	Description
codebase_search	Semantic + lexical search across the codebase. Returns ranked snippets with line numbers.
graph_search	Search the knowledge graph by node name prefix.
graph_neighbors	Get callers, callees, imports, and references around a code entity.
graph_stats	Graph health: total nodes, edges, and breakdown by kind.
graph_list_codebases	List all indexed codebases.

Routing Enrichment

MCP tools can be used as routing enrichment providers. When a message arrives, the routing framework automatically searches the codebase and injects relevant context before the LLM responds:

# routing.toml
[[providers]]
name = "deep-context"
type = "tool"

[[providers.tools]]
tool_name = "mcp_ugent-context-mcp_codebase_search"
input_mode = "query_passthrough"
summary_format = "search"
default_params = { max_results = 12, snippet_lines = 20 }

Custom Headers

Some MCP servers require authentication headers:

[mcp.services.my-service.headers]
Authorization = "Bearer your-token"
X-Custom-Header = "value"

Connection Resilience

• Exponential backoff retry on connection failures
• reinit_on_expired_session (default: true) — automatically re-initializes when the server returns 404 for an existing session ID
• initialized_ack_mode = "lenient" — tolerates servers that don't send a proper initialized acknowledgment

Tool Name Convention

MCP tools are registered with the prefix mcp_ or mcp__ followed by the service name and tool name. For example, the Exa web search tool appears as mcp_exa_web_search_exa.

Disable Flags

Skip all MCP servers for a session:

ugent --disable-mcp

The MCP manager is not created — MCP status hooks and auto-connect are fully skipped.

Timeout Configuration

Per-service timeout overrides:

[mcp.services.context-mcp]
tool_timeout_secs = 30

For high-depth graph_neighbors calls, consider setting a higher timeout to avoid default expiration.