MCP Server Integration with Agent Reach: Exposing Health Diagnostics via the Model Control Protocol

Agent Reach exposes its channel diagnostic capabilities as an MCP (Model Control Protocol) server through agent_reach/integrations/mcp_server.py, enabling AI agents to query installation status via the get_status tool that returns formatted reports from doctor_report().

Agent Reach is an open-source Python library that manages and diagnoses third-party "channel" tools. When you need to integrate these diagnostics into AI-agent workflows using the Model Control Protocol (MCP), the repository provides a lightweight integration layer that bridges Agent Reach's health-check system with MCP-compatible clients.

Architecture of the MCP Integration

The integration follows a three-layer architecture that separates configuration, diagnostics, and protocol handling. This design ensures the MCP server remains a thin wrapper around existing Agent Reach functionality.

Configuration Management

At the base layer, agent_reach/config.py handles user settings loaded from ~/.agent-reach/config.yaml. The Config class provides validation helpers like Config.is_configured() that determine whether the system is ready for diagnostic operations.

Diagnostic Engine

The middle layer consists of agent_reach/core.py and agent_reach/doctor.py. The AgentReach class in core.py exposes two primary methods:

• doctor() → Returns a raw dictionary of diagnostic results
• doctor_report() → Returns a human-readable formatted health report

The underlying doctor.py implements the actual health-check logic that inspects each channel's availability.

MCP Protocol Wrapper

The top layer, agent_reach/integrations/mcp_server.py, wraps these diagnostics for MCP consumption. It imports from mcp.server, mcp.server.stdio, and mcp.types to create a standardized interface.

Implementing the MCP Server

The implementation follows MCP conventions for tool registration and request handling.

Server Initialization and Dependency Check

The module first validates MCP availability through a HAS_MCP flag. If the mcp package is missing, the script outputs "MCP not installed. Install: pip install agent-reach[mcp]" and exits gracefully.

When dependencies are present, create_server() instantiates a Server("agent-reach") object alongside Config and AgentReach instances (internally referenced as eyes):

from agent_reach.integrations.mcp_server import create_server

server = create_server()  # Returns configured Server instance

Tool Registration

The @server.list_tools() decorator registers available capabilities. The integration exposes a single tool named get_status, which includes a description explaining that it returns "which channels are installed and active":

# Tool schema exposed to MCP clients

{
    "name": "get_status",
    "description": "Returns which channels are installed and active"
}

Request Handling and Response Formatting

The @server.call_tool() decorator handles incoming requests. When invoked with get_status, the handler calls eyes.doctor_report() to retrieve the formatted health output. Invalid tool names return an "Unknown tool" error message.

Results are wrapped in TextContent objects (MCP's standard text payload) before transmission:

# Response structure returned to MCP clients

[TextContent(type="text", text="formatted diagnostic report")]

Running and Querying the Server

You can start the MCP server via command line or embed it in existing applications.

Starting via Command Line

Execute the module directly to launch a stdio-based MCP server:

python -m agent_reach.integrations.mcp_server

This starts the event loop and listens for MCP requests on standard input/output streams.

Querying from an MCP Client

Once running, MCP clients can discover and invoke the tool:

from mcp.client import Client

async def check_agent_reach():
    client = Client()
    await client.connect()
    
    # Discover available tools

    tools = await client.list_tools()
    # Returns: [{'name': 'get_status', ...}]

    
    # Execute diagnostic query

    result = await client.call_tool("get_status", {})
    print(result[0]["text"])  # Human-readable channel status

Embedded Server Integration

For custom workflows, instantiate the server programmatically:

import asyncio
from agent_reach.integrations.mcp_server import create_server
from mcp.server.stdio import stdio_server

async def run_server():
    server = create_server()
    async with stdio_server() as (read_stream, write_stream):
        await server.run(
            read_stream, 
            write_stream, 
            server.create_initialization_options()
        )

if __name__ == "__main__":
    asyncio.run(run_server())

Summary

• The MCP integration resides in agent_reach/integrations/mcp_server.py, providing a standards-compliant interface for AI agents.
• The server exposes a single tool, get_status, which returns formatted diagnostics via the doctor_report() method.
• Dependency checking via HAS_MCP ensures graceful degradation when the MCP library is not installed.
• The server supports both stdio transport for CLI usage and programmatic embedding for custom applications.
• Underlying diagnostics rely on agent_reach/core.py and agent_reach/doctor.py, while configuration management uses agent_reach/config.py.

Frequently Asked Questions

What MCP tool does Agent Reach expose?

Agent Reach exposes a single tool named get_status. This tool returns a human-readable diagnostic report indicating which third-party channels are installed and active on the system.

How does the server handle missing MCP dependencies?

The integration checks for the mcp package availability at startup using the HAS_MCP flag. If the package is missing, the server prints "MCP not installed. Install: pip install agent-reach[mcp]" and exits immediately, preventing runtime import errors.

Can I run the Agent Reach MCP server without using the command line?

Yes. While you can run the server via python -m agent_reach.integrations.mcp_server, you can also import create_server() from agent_reach.integrations.mcp_server to embed the server within larger async applications or custom transport layers.

What information does the get_status tool return?

The tool returns the output of AgentReach.doctor_report(), which is a formatted text summary of all diagnostic checks performed by agent_reach/doctor.py. This includes the installation status and availability of each configured channel tool in the Agent Reach ecosystem.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}