MCP Integration¶

Lango acts as an MCP client, connecting to one or more external MCP servers to discover and invoke their tools. Discovered tools are automatically adapted into native agent.Tool instances and passed through the full middleware chain (hooks, approval, learning).

Architecture¶

graph LR
    subgraph Lango
        W[App Wiring<br/>initMCP] --> SM[ServerManager]
        SM --> SC1[ServerConnection<br/>stdio]
        SM --> SC2[ServerConnection<br/>http]
        SM --> SC3[ServerConnection<br/>sse]
        SM --> AT[AdaptTools]
        AT --> AG[Agent Tools]
    end

    subgraph External
        MCP1[MCP Server<br/>stdio process]
        MCP2[MCP Server<br/>HTTP endpoint]
        MCP3[MCP Server<br/>SSE endpoint]
    end

    SC1 -- "CommandTransport" --> MCP1
    SC2 -- "StreamableClientTransport" --> MCP2
    SC3 -- "SSEClientTransport" --> MCP3

    style SM fill:#2980b9,color:#fff
    style AT fill:#2980b9,color:#fff

Key Components¶

Transport Types¶

Lango supports three MCP transport types:

For http and sse transports, custom HTTP headers (e.g., authentication) are injected via a headerRoundTripper on every request.

Configuration¶

Global Settings¶

Per-Server Settings¶

Each server under mcp.servers.<name> supports:

Multi-Scope Config Merging¶

MCP server definitions are loaded from three scopes and merged by server name, with higher-priority scopes overriding lower ones:

The JSON file format for user and project scopes:

{
  "mcpServers": {
    "filesystem": {
      "transport": "stdio",
      "command": "npx",
      "args": ["@modelcontextprotocol/server-filesystem", "/home/user/docs"]
    },
    "github": {
      "transport": "http",
      "url": "https://mcp.github.com/v1",
      "headers": {
        "Authorization": "Bearer ${GITHUB_TOKEN}"
      },
      "safetyLevel": "moderate"
    }
  }
}

This allows teams to share project-level servers via .lango-mcp.json while individual developers add personal servers in ~/.lango/mcp.json.

Tool Naming Convention¶

Tools discovered from MCP servers are registered with the naming pattern:

mcp__{serverName}__{toolName}

For example, a read_file tool from a server named filesystem becomes mcp__filesystem__read_file. This convention follows the Claude Code naming standard and prevents name collisions between tools from different servers.

Connection Lifecycle¶

Startup¶

1. initMCP checks mcp.enabled; exits early if disabled
2. MergedServers loads and merges configs from all three scopes
3. ServerManager.ConnectAll connects to all enabled servers concurrently
4. Each ServerConnection.Connect creates the appropriate transport, establishes a client session, and discovers tools/resources/prompts
5. Connection failures are logged as warnings; other servers continue normally
6. AdaptTools converts all discovered MCP tools into agent.Tool instances
7. Health check goroutines start for successfully connected servers

Health Checks¶

Connected servers are periodically pinged at the configured healthCheckInterval. If a ping fails:

1. The server state transitions to StateFailed
2. If autoReconnect is enabled, a background goroutine attempts reconnection with exponential backoff (1s, 2s, 4s, ..., capped at 30s)
3. After maxReconnectAttempts failures, the server remains in failed state

Shutdown¶

The MCP ServerManager is registered with the lifecycle registry at PriorityNetwork. On app shutdown:

1. Each ServerConnection.Disconnect signals health check goroutines to stop via stopCh
2. Active client sessions are closed
3. Server state transitions to StateStopped

Connection States¶

Management Tools¶

Two built-in tools are registered under the "mcp" catalog category when MCP is active:

Security¶

• Server authentication headers and environment variables containing secrets are registered with the secret scanner to prevent leakage in logs or agent output.
• The lango mcp CLI command is blocked from agent shell execution via the blockLangoExec guard, preventing the agent from modifying its own MCP configuration.

Quick Start¶

1. Enable MCP in your config:

   lango config set mcp.enabled true
   

2. Add a server (e.g., a filesystem MCP server):

   lango mcp add filesystem \
       --type stdio \
       --command "npx" \
       --args "@modelcontextprotocol/server-filesystem,/home/user/docs" \
       --scope project
   

3. Test connectivity:

   lango mcp test filesystem
   

4. Verify tools are available:

   lango mcp get filesystem
   

5. Use it -- the agent can now invoke tools like mcp__filesystem__read_file during conversations.

CLI Reference¶

For the full CLI command reference, see MCP Commands.