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

You can integrate Agent Reach with MCP servers by running the 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 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 – 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 – 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 – 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. 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:

pip install agent-reach[mcp]

Starting the Server

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

python -m agent_reach.integrations.mcp_server

The main() coroutine in 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:

• @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

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

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:

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 and provides a stdio-based MCP server.
• Single tool exposure: The get_status tool calls doctor_report() from 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 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 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 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 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.

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