docs(http): document curl session lifecycle

[haranishi]

Description

Adds connection instructions for #1052, where requests sent with curl after initialize fail with “Missing session ID”. Passing the MCP-Session-Id from the initialization response and the negotiated MCP-Protocol-Version to subsequent requests allows separate HTTP connections to use the same MCP session.

Implemented the documentation changes proposed in the issue. There are no changes to server behavior.

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update
• Refactoring
• Test update

Changes Made

• Adds a curl example covering initialization, notification, tool listing, instance reading, and session termination.
• Explains the correct format for notifications/initialized, JSON/SSE responses, and recovery steps for 400/404 responses.
• Links to the guide from the server README, troubleshooting documentation, and sidebar.
• Points readers to the local CLI, which needs no MCP session, and to the steps for choosing among multiple Editors.

Compatibility / Package Source

• Unity version(s) tested: No changes to C# or Unity settings. Tests that run in Unity are not applicable.
• Package source used: Server source from beta. Base commit 142ea0af.
• Git package resolved hash: Not applicable.

Testing/Screenshots/Recordings

• Python tests: 1,575 passed, 18 skipped.
• Unity EditMode tests
• Unity PlayMode tests
• Package import/compile check
• Not applicable: No changes to Unity code or packages.

Reproduced a 400 response caused by a missing session header against a dedicated real HTTP server. With the headers included, verified initialization 200, notification 202, listing and reading 200, termination 200, and terminated session 404. No long-running GET connection was used.

Ran the guide’s Bash code exactly as written and verified the response contents. The website production build and the generated reference consistency check also passed. The 4 specified Unity versions were skipped because they were not installed.

Documentation Updates

• I have added/removed/modified tools or resources
• Updated generated tool/resource documentation

Related Issues

Fixes #1052 — Documentation changes for the HTTP connection procedure proposed in the issue.

Additional Notes

Verification used Bash on macOS and a local HTTP server. The individual client applications on Windows were not verified. Actual session IDs, local paths, credentials, and verification logs are not included in the public diff or PR description.

Fork CI verification

Checked the GitHub Actions results for the same commit 0d1ace8e5787ff5e9705ba323aed2f21237e9679. The Python tests succeeded, as did the harness tests that run without Unity.

The docs build succeeded.

The upstream GitHub Actions are waiting for a maintainer to approve the run for the current commit. The CI successes above are results from runs on the fork that verified the same commit.

Summary by CodeRabbit

• Documentation
  • Added a guide for managing HTTP client sessions, including initialization, reusing session details, making requests, and recovering from errors.
  • Added troubleshooting advice for including required session headers on follow-up requests.
  • Updated PyPI installation instructions to link to the session guide for curl and custom HTTP clients.
  • Added the new guide to the Guides navigation.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: 9bc630b5-81a1-4b3e-923f-3475da0be90c

📥 Commits

Reviewing files that changed from the base of the PR and between 142ea0a and 0d1ace8.

📒 Files selected for processing (4)

• Server/README.md
• website/docs/guides/http-client-sessions.md
• website/docs/guides/troubleshooting.md
• website/sidebars.js

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 8 remain after this review.

📝 Walkthrough

The changes add an HTTP client session guide with a curl workflow, troubleshooting information, and guidance in the server README. The Guides sidebar now links to the new guide.

Changes: HTTP client session documentation

Layer / File(s)	Summary
Document and surface HTTP session guidance website/docs/guides/http-client-sessions.md, Server/README.md, website/docs/guides/troubleshooting.md, website/sidebars.js	The new guide describes session initialization, required headers, tool and resource requests, session deletion, error recovery, and the separate local CLI route. The README and troubleshooting page direct readers to the guide, and the sidebar lists it.

Priority: ➖ Normal

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Other · Severity of issue fixed: Medium

Suggested reviewers: scriptwonder

Merge Risk: ⚪ Minimal · up to 0d1ac

The new curl guide matches the server’s session requirements, and no actionable merge risk remains.

Pre-merge checks · 5

Passed checks (5 passed)

Check name	Status	Explanation
Title check		The title is concise and accurately identifies the main change: documenting the curl HTTP session lifecycle.
Description check		The description is complete and matches the template. It explains the documentation change, lists the affected areas, records testing and verification results, identifies compatibility details, and li…
Linked Issues check		Issue #1052 allows documentation of the session mechanism as an outcome. The new HTTP client session guide documents extracting MCP-Session-Id, sending it with MCP-Protocol-Version on every later …
Out of Scope Changes check		The reviewed changes are documentation updates related to issue #1052. They add the HTTP session guide, link it from the server README and troubleshooting documentation, and add the guide to the sideb…
Docstring Coverage		No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 1…

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[haranishi]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.