# How to Integrate Agent Reach with MCP Servers: Complete Setup Guide

> Integrate Agent Reach with MCP servers effortlessly using the mcp_server.py module. Get formatted diagnostic reports and streamline your setup with our complete guide.

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

---

**You can integrate Agent Reach with MCP servers by running the [`mcp_server.py`](https://github.com/Panniantong/Agent-Reach/blob/main/mcp_server.py) integration module, which exposes the `get_status` tool that returns formatted diagnostic reports from the Agent Reach core.**

Agent Reach is a diagnostic CLI and library for managing third-party channel integrations. To bridge Agent Reach with AI agents through the Model Control Protocol (MCP), the repository provides a dedicated integration layer in [`agent_reach/integrations/mcp_server.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/integrations/mcp_server.py) that registers diagnostic capabilities as callable MCP tools.

## Understanding the MCP Integration Architecture

The integration connects Agent Reach’s internal diagnostic engine to the MCP framework through three core layers.

### Core Diagnostic Components

The MCP server relies on two primary internal modules to gather health data:

- **[`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py)** – Implements the `Config` class that loads user settings from `~/.agent-reach/config.yaml` and provides validation helpers like `Config.is_configured()`.

- **[`agent_reach/core.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/core.py)** – Wraps configuration into an `AgentReach` class (instantiated as `eyes` in the server code) that exposes two key methods: `doctor()` returns a raw diagnostic dictionary, while `doctor_report()` returns a human-readable formatted health report.

- **[`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py)** – Contains the `check_all()` function that performs the actual health checks on each configured channel, returning availability status for tools like Twitter-CLI, yt-dlp, and mcporter.

### The MCP Server Bridge

The bridge implementation lives in [`agent_reach/integrations/mcp_server.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/integrations/mcp_server.py). The module first attempts to import MCP components (`mcp.server`, `mcp.server.stdio`, `mcp.types`) and sets a `HAS_MCP` flag. If the import fails, the server exits with a prompt to install the MCP dependency using `pip install agent-reach[mcp]`.

The `create_server()` function instantiates a `Server("agent-reach")` object, creates a `Config` instance, and initializes an `AgentReach` object named `eyes` that serves as the diagnostic engine.

## Setting Up the MCP Server

### Installation Requirements

Ensure you have the MCP extras installed:

```bash
pip install agent-reach[mcp]

```

### Starting the Server

Launch the MCP server using the module’s entry point:

```bash
python -m agent_reach.integrations.mcp_server

```

The `main()` coroutine in [`mcp_server.py`](https://github.com/Panniantong/Agent-Reach/blob/main/mcp_server.py) creates the server, opens a stdio-based transport using `stdio_server()`, and runs the asynchronous server loop. The server communicates over standard input/output streams, making it compatible with any MCP client that supports stdio transport.

## Registering the get_status Tool

The integration exposes a single MCP tool named `get_status` that returns the current health status of all Agent Reach channels.

Tool registration uses two decorators defined in [`mcp_server.py`](https://github.com/Panniantong/Agent-Reach/blob/main/mcp_server.py):

- **`@server.list_tools()`** – Registers the available tool list. The `get_status` tool is described as returning "which channels are installed and active".

- **`@server.call_tool()`** – Handles execution. When the client calls `get_status`, the handler invokes `eyes.doctor_report()` to retrieve the formatted diagnostic output. For unknown tool names, it returns an error message. The result is wrapped in `TextContent` (from `mcp.types`) and returned to the client.

## Querying Diagnostics from an MCP Client

Once the server is running, any MCP client can discover and invoke the tool.

### Listing Available Tools

```python
from mcp.client import Client

client = Client()
await client.connect()  # Opens stdio streams automatically

tools = await client.list_tools()
print(tools)

# Output: [{'name': 'get_status', 'description': 'Returns which channels are installed and active'}]

```

### Calling the get_status Tool

```python
result = await client.call_tool("get_status", {})
print(result[0]["text"])

# Returns formatted health report from Agent Reach doctor_report()

```

### Embedding in Custom Applications

You can embed the server in your own async application:

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

async def run_custom_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_custom_server())

```

## Summary

- **Agent Reach MCP integration** resides in [`agent_reach/integrations/mcp_server.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/integrations/mcp_server.py) and provides a stdio-based MCP server.
- **Single tool exposure**: The `get_status` tool calls `doctor_report()` from [`agent_reach/core.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/core.py) to return formatted diagnostics.
- **Dependency handling**: The server gracefully exits if the `mcp` package is missing, prompting for `pip install agent-reach[mcp]`.
- **Architecture**: Combines `Config` (settings), `AgentReach` (diagnostic wrapper), and `doctor.check_all()` (health logic) behind the MCP protocol.
- **Invocation**: Start with `python -m agent_reach.integrations.mcp_server` and query via any MCP client using the `get_status` tool name.

## Frequently Asked Questions

### What is the difference between doctor() and doctor_report() in Agent Reach?

The `doctor()` method in [`agent_reach/core.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/core.py) returns a raw Python dictionary containing the diagnostic results from `doctor.check_all()`, while `doctor_report()` returns a formatted string optimized for human readability. The MCP integration specifically uses `doctor_report()` for the `get_status` tool to provide readable output to AI agents.

### Can I expose additional Agent Reach functionality through the MCP server?

Yes. You can extend [`agent_reach/integrations/mcp_server.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/integrations/mcp_server.py) by adding new tool definitions under the `@server.list_tools()` decorator and corresponding handlers under `@server.call_tool()`. Any public method from the `AgentReach` class in [`agent_reach/core.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/core.py) can be exposed as an MCP tool by wrapping its return value in `TextContent` or appropriate MCP types.

### What transport protocols does the Agent Reach MCP server support?

The current implementation in [`mcp_server.py`](https://github.com/Panniantong/Agent-Reach/blob/main/mcp_server.py) uses stdio (standard input/output) transport via `stdio_server()`. This is the default MCP transport for local process communication. While the code structure supports swapping transports, the built-in module specifically initializes the stdio server in its `main()` coroutine.

### Why does the server exit with a message about MCP not being installed?

The server checks for the presence of the `mcp` Python package at startup and sets `HAS_MCP = False` if the import fails. This defensive check prevents runtime errors when the optional MCP dependency is missing. Install the required package using `pip install agent-reach[mcp]` to resolve this.