# How MCP Server Integration Works with mcporter in Agent Reach

> Discover how MCP server integration uses mcporter in Agent Reach to expose diagnostic capabilities via JSON-RPC over stdio. Query system status externally with ease.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: internals
- Published: 2026-07-11

---

**Agent Reach exposes its internal diagnostic capabilities as an MCP-compatible tool via a lightweight server that uses `mcporter` as the underlying transport layer, enabling external processes to query system status through JSON-RPC over stdio.**

The `Panniantong/Agent-Reach` repository implements a standards-based **MCP (Message-Cross-Process) server** that bridges the framework's internal health checks with any MCP-capable client. This integration allows the `mcporter` package to discover and invoke Agent Reach tools from the command line or other agent processes.

## MCP Server Architecture and Bootstrap

The MCP server implementation resides in [`agent_reach/integrations/mcp_server.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/integrations/mcp_server.py). When executed as a module, the `main()` coroutine initializes the server infrastructure.

The bootstrap process follows these steps:

1. **Server instantiation** – Creates a `Server` instance named **"agent-reach"** (line 32) that exposes the MCP protocol.
2. **Core initialization** – Constructs an `AgentReach` object (line 34) that loads configuration and initializes the internal **doctor** logic used for system diagnostics.
3. **Transport startup** – Launches the stdio server via `mcp.server.stdio.stdio_server` (lines 60-64), which listens for JSON-RPC messages on stdin and writes responses to stdout.

This architecture ensures that Agent Reach can run as a standalone process that `mcporter` can connect to using standard process-based communication.

## Tool Registration and the get_status Implementation

The server registers a single MCP tool called **`get_status`** that surfaces the framework's internal health data to external clients.

Inside `create_server()`:

- The `@server.list_tools()` decorator (lines 38-42) registers the tool with a descriptive schema indicating it returns the current Agent Reach status, including installed channels and their activity state.
- The `@server.call_tool()` handler (lines 44-55) implements the actual execution logic.

When invoked, the handler validates the tool name and calls `eyes.doctor_report()`—the same method used by the CLI's `doctor` command. The result is serialized to JSON (lines 48-53) and returned to the client. Errors are caught and returned as plain text to prevent transport failures.

## Transport Layer and mcporter Connection

Agent Reach relies on **`mcporter`** to provide the MCP transport layer and client-side tooling. The server uses **stdio transport**, which is the standard expectation for `mcporter` integrations.

Key integration points include:

- **Process spawning** – The CLI can install `mcporter` via `_install_mcporter()` in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py), ensuring the transport package is available on the host system.
- **UTF-8 handling** – [`agent_reach/utils/process.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/utils/process.py) provides `mcporter_utf8_env_args()` to ensure proper encoding when spawning `mcporter` processes, preventing character set mismatches during JSON-RPC communication.
- **Protocol compliance** – By using `mcp.server.stdio.stdio_server`, Agent Reach adheres to the MCP specification that `mcporter` expects: a long-running process that reads JSON-RPC requests from stdin and writes responses to stdout.

This design allows any MCP client—including the `mcporter` CLI itself—to connect without custom networking configuration.

## Practical Usage Examples

### Starting the MCP Server

Run the server directly as a Python module. It will block and listen for MCP commands on stdio:

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

```

For background operation, use your shell's process management:

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

```

### Querying Status via mcporter CLI

Once the server is running, use `mcporter` to call the exposed tool:

```bash
mcporter call 'get_status()' --json

```

The expected JSON response includes channel status, backend health, and configuration warnings:

```json
{
  "channels": {
    "twitter": "active",
    "youtube": "inactive",
    "exa_search": "active"
  },
  "backends": ["mcporter"],
  "message": "All systems operational"
}

```

### Programmatic Access Without MCP

For internal use within Python applications, access the same diagnostic data directly without starting the MCP server:

```python
from agent_reach.core import AgentReach
from agent_reach.config import Config

cfg = Config()
reach = AgentReach(cfg)

# Obtain the same report that the MCP get_status tool returns

status = reach.doctor_report()
print(status)

```

## Summary

- **MCP server location**: Implemented in [`agent_reach/integrations/mcp_server.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/integrations/mcp_server.py) as a stdio-based JSON-RPC server.
- **Exposed tool**: The `get_status` tool wraps `doctor_report()` from [`agent_reach/core.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/core.py) to expose channel and backend health.
- **Transport dependency**: `mcporter` provides the command-line client and transport expectations; Agent Reach ensures compatibility via stdio and UTF-8 environment helpers in [`agent_reach/utils/process.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/utils/process.py).
- **Execution model**: Run with `python -m agent_reach.integrations.mcp_server` and interact via `mcporter call` or any MCP-compatible client.

## Frequently Asked Questions

### What is the relationship between Agent Reach and mcporter?

Agent Reach implements the MCP server protocol, while `mcporter` acts as the transport layer and client. Agent Reach does not embed `mcporter` logic directly; instead, it conforms to the MCP stdio transport specification that `mcporter` expects, allowing the two to communicate via JSON-RPC over standard input/output streams.

### How do I troubleshoot connection issues between mcporter and Agent Reach?

Verify that the MCP server is running and listening on stdio. Check that `mcporter` is installed (the CLI can install it via `_install_mcporter()` in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)). Ensure UTF-8 encoding is properly configured—the `mcporter_utf8_env_args()` helper in [`agent_reach/utils/process.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/utils/process.py) handles this automatically when spawning processes programmatically.

### Can I extend the MCP server with additional tools?

Yes. In [`agent_reach/integrations/mcp_server.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/integrations/mcp_server.py), add new functions decorated with `@server.list_tools()` to register additional schemas, and implement the corresponding logic in `@server.call_tool()` handlers. Each new tool can access the `AgentReach` core instance (`eyes`) to interact with internal APIs, following the pattern established by `get_status`.

### Is the doctor_report() method available outside the MCP context?

Absolutely. The `doctor_report()` method is defined in [`agent_reach/core.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/core.py) within the `AgentReach` class. It powers both the CLI `doctor` command and the MCP `get_status` tool, making it available for programmatic health checks without starting the JSON-RPC server.