Skip to content

docs: add Unix socket and SSE transport to MCP Integration Guide (#6739) #6855

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
bryanadenhq merged 2 commits into from
Mar 31, 2026
Merged

docs: add Unix socket and SSE transport to MCP Integration Guide (#6739) #6855

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
eabb179
docs: add Unix socket and SSE transport types to MCP Integration Guide
Ttian18 Mar 29, 2026
f9fdaf5
docs: clarify required vs optional fields for Unix and SSE transports
Ttian18 Mar 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
91 changes: 88 additions & 3 deletions core/MCP_INTEGRATION_GUIDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ This guide explains how to integrate Model Context Protocol (MCP) servers with t

The framework provides built-in support for MCP servers, allowing you to:

- **Register MCP servers** via STDIO or HTTP transport
- **Register MCP servers** via STDIO, HTTP, Unix socket, or SSE transport
- **Auto-discover tools** from registered servers
- **Use MCP tools** seamlessly in your agents
- **Manage multiple MCP servers** simultaneously
Expand Down Expand Up @@ -104,6 +104,48 @@ runner.register_mcp_server(
- `url`: Base URL of the MCP server
- `headers`: HTTP headers to include (optional)

### Unix Socket Transport

Best for same-host inter-process communication with lower overhead than TCP:

```python
runner.register_mcp_server(
name="local-ipc-tools",
transport="unix",
url="http://localhost",
socket_path="/tmp/mcp_server.sock",
headers={
"Authorization": "Bearer token"
}
)
```

**Configuration:**

- `url`: Base URL for HTTP requests over the socket (e.g., `"http://localhost"`)
- `socket_path`: Absolute path to the Unix socket file (e.g., `"/tmp/mcp_server.sock"`)
- `headers`: HTTP headers to include (optional)

@coderabbitai coderabbitai Bot Mar 29, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Clarify required vs optional fields to match runtime behavior.

The new sections describe fields but don’t explicitly mark required/optional status, and Unix url is presented like a required input though implementation defaults to http://localhost when omitted (core/framework/runner/mcp_client.py:235-265). Also, SSE url is required in code (core/framework/runner/mcp_client.py:301-335).

✏️ Proposed doc clarification 
- - `url`: Base URL for HTTP requests over the socket (e.g., `"http://localhost"`)
- - `socket_path`: Absolute path to the Unix socket file (e.g., `"/tmp/mcp_server.sock"`)
- - `headers`: HTTP headers to include (optional)
+ - `socket_path`: Absolute path to the Unix socket file (required)
+ - `url`: Base URL for HTTP requests over the socket (optional, defaults to `"http://localhost"`)
+ - `headers`: HTTP headers to include (optional)

- - `url`: SSE endpoint URL (e.g., `"http://localhost:8000/sse"`)
- - `headers`: HTTP headers for the SSE connection (optional)
+ - `url`: SSE endpoint URL (required)
+ - `headers`: HTTP headers for the SSE connection (optional)

Also applies to: 146-147

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@core/MCP_INTEGRATION_GUIDE.md` around lines 125 - 127, The doc currently
lists `url`, `socket_path`, and `headers` without stating which are required;
update the MCP_INTEGRATION_GUIDE.md to explicitly mark which fields are required
vs optional to match runtime behavior in core/framework/runner/mcp_client.py:
mark `url` as optional (defaulting to "http://localhost" when omitted) and
`socket_path` and `headers` as optional if that matches code, and explicitly
mark the SSE `url` (the stream endpoint used by the SSE logic in mcp_client.py)
as required; ensure the descriptions note the default for `url` and call out
that omitting the SSE `url` will cause runtime errors so it must be provided.


### SSE Transport

Best for real-time, event-driven connections using the MCP SDK's SSE client:

```python
runner.register_mcp_server(
name="streaming-tools",
transport="sse",
url="http://localhost:8000/sse",
headers={
"Authorization": "Bearer token"
}
)
```

**Configuration:**

- `url`: SSE endpoint URL (e.g., `"http://localhost:8000/sse"`)
- `headers`: HTTP headers for the SSE connection (optional)

## Using MCP Tools in Agents

Once registered, MCP tools are available just like any other tool:
Expand Down Expand Up @@ -258,7 +300,32 @@ runner.register_mcp_server(
)
```

### 3. Handle Cleanup
### 3. Use Unix Socket for Same-Host IPC

When both the agent and MCP server run on the same machine, Unix sockets avoid TCP overhead:

```python
runner.register_mcp_server(
name="fast-local-tools",
transport="unix",
url="http://localhost",
socket_path="/tmp/mcp_server.sock"
)
```

### 4. Use SSE for Streaming and Real-Time Tools

SSE transport maintains a persistent connection, ideal for event-driven servers:

```python
runner.register_mcp_server(
name="realtime-tools",
transport="sse",
url="http://realtime-server:8000/sse"
)
```

### 5. Handle Cleanup

Always clean up MCP connections when done:

Expand All @@ -280,7 +347,7 @@ async with AgentRunner.load("exports/my-agent") as runner:
# Automatic cleanup
```

### 4. Tool Name Conflicts
### 6. Tool Name Conflicts

If multiple MCP servers provide tools with the same name, the last registered server wins. To avoid conflicts:

Expand Down Expand Up @@ -315,6 +382,24 @@ If HTTP transport fails:
2. Check firewall settings
3. Verify the URL and port are correct

### Unix Socket Not Connecting

If Unix socket transport fails:

1. Verify the socket file exists: `ls -la /tmp/mcp_server.sock`
2. Check file permissions on the socket
3. Ensure no other process has locked the socket
4. Verify the `url` field is set (e.g., `"http://localhost"`)

### SSE Connection Issues

If SSE transport fails:

1. Verify the server supports SSE at the given URL
2. Check that the `mcp` Python package is installed (`pip install mcp`)
3. Ensure the SSE endpoint is accessible: `curl http://localhost:8000/sse`
4. Check for firewall or proxy issues blocking long-lived connections

## Example: Full Agent with MCP Tools

Here's a complete example of an agent that uses MCP tools:
Expand Down
Loading