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

[Ttian18]

Description

The MCP client supports four transport types (stdio, http, unix, sse),
but the MCP Integration Guide only documents STDIO and HTTP. Unix and SSE were
added in PR #6531 but docs weren't updated.

Type of Change

• Documentation update

Related Issues

Fixes #6739

Changes Made

• Transport Types section — add Unix Socket Transport and SSE Transport
  subsections with configuration fields, required/optional status, and examples
• Overview line — update "via STDIO or HTTP transport" to include all four
• Best Practices section — add guidance on when to choose Unix socket
  (same-host IPC) and SSE (streaming/real-time) over HTTP/STDIO
• Troubleshooting section — add debugging steps for Unix socket and SSE
  connection issues

Testing

• MCP client tests pass (uv run pytest core/tests/test_mcp_client.py -v)
• Config fields verified against MCPServerConfig dataclass in
  core/framework/runner/mcp_client.py
• Documentation style matches existing STDIO/HTTP sections

Checklist

• My code follows the project's style guidelines
• I have performed a self-review of my code
• My changes generate no new warnings
• New and existing unit tests pass locally with my changes

Summary by CodeRabbit

• Documentation
  • Integration guide updated to include Unix socket and SSE transport options (configuration fields and examples), alongside STDIO/HTTP.
  • Best-practices reordered to highlight Unix socket for same-host IPC and SSE for streaming/real-time tools; other items renumbered.
  • Added troubleshooting for Unix socket connection issues and for SSE connection problems and long-lived connection filtering.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: eeb4d7fb-e3ce-4d63-8a88-1c1e10a1c4c3

📥 Commits

Reviewing files that changed from the base of the PR and between eabb179 and f9fdaf5.

📒 Files selected for processing (1)

• core/MCP_INTEGRATION_GUIDE.md

✅ Files skipped from review due to trivial changes (1)

• core/MCP_INTEGRATION_GUIDE.md

---

📝 Walkthrough

Walkthrough

Updated the MCP Integration Guide to document Unix socket and SSE transports in addition to STDIO and HTTP, adding configuration examples, best-practice guidance, and troubleshooting steps for both transports.

Changes

Cohort / File(s)

Summary

MCP Transport Documentation core/MCP_INTEGRATION_GUIDE.md

Expanded transport overview to include unix and sse. Added sections for Unix Socket Transport (fields: transport="unix", socket_path, example url) and SSE Transport (fields: transport="sse", url, optional headers, example). Reordered Best Practices to add "Use Unix Socket for Same-Host IPC" and "Use SSE for Streaming and Real-Time Tools", moved "Handle Cleanup" and renumbered "Tool Name Conflicts". Added troubleshooting for Unix socket connection (socket existence/permissions/locking, url verification) and SSE connection issues (SSE support, mcp package, endpoint accessibility, long-lived connection filtering).

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐰 New transports hopped in, snug and neat,
Unix sockets whisper, SSE streams greet,
Examples and tips penned line by line,
STDIO and HTTP now join the shine,
Docs sprout new paths — a rabbit's small feat.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The pull request title clearly summarizes the main change: adding documentation for Unix socket and SSE transport types to the MCP Integration Guide.
Linked Issues check	✅ Passed	The pull request addresses all acceptance criteria from issue #6739: documents Unix socket and SSE transports with configuration fields and examples, updates the overview to include all four transports, and adds Best Practices and Troubleshooting sections.
Out of Scope Changes check	✅ Passed	All changes are scoped to documentation updates for the MCP Integration Guide, directly addressing the linked issue requirements without introducing unrelated modifications.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@core/MCP_INTEGRATION_GUIDE.md`:
- Around line 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.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 5b4649a0-ae55-454b-8733-700a15db37ea

📥 Commits

Reviewing files that changed from the base of the PR and between eba7524 and eabb179.

📒 Files selected for processing (1)

• core/MCP_INTEGRATION_GUIDE.md

[coderabbitai]

⚠️ 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.