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

> Integrate MCP server with Agent Reach to expose health diagnostics. Use the get_status tool to query installation status and get formatted reports. Learn how to implement this powerful integration.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: how-to-guide
- Published: 2026-06-22

---

**Agent Reach exposes its channel diagnostic capabilities as an MCP (Model Control Protocol) server through [`agent_reach/integrations/mcp_server.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/core.py)** and **[`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py)**. The **AgentReach** class in [`core.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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*):

```python
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":

```python

# 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:

```python

# 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:

```bash
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:

```python
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:

```python
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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/core.py)** and **[`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py)**, while configuration management uses **[`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py). This includes the installation status and availability of each configured channel tool in the Agent Reach ecosystem.