docs(mcp): document long-running tool calls and Tasks roadmap

[mateo-berri]

Relevant issues

Came out of a LANL support thread asking whether the MCP gateway supports the new Tasks extension and, if not, what the recommended path is for long-running tool calls

Linear ticket

LIT-3784 (Align MCP server with the 2026-07-28 stateless spec: Tasks extension + session removal)

Pre-Submission checklist

• My PR's scope is as isolated as possible; it only solves 1 specific problem
• I have added meaningful tests
• My PR passes all unit tests on make test-unit
• I have requested a Greptile review

Screenshots / Proof of Fix

Docs-only change, so there is no runtime behavior to exercise against a live proxy. The artifact is the rendered README at litellm/proxy/_experimental/mcp_server/README.md

Type

📖 Documentation

Changes

Adds a developer reference next to the MCP server that captures how the gateway handles long-running tool calls today and where the work is headed. The knowledge currently only lives in the server.py progress-forwarding path and in the support thread, so this writes it down

What it documents:

• Progress notifications: a host passes a progressToken in the tools/call _meta; the gateway captures it and relays upstream progress back to the host session via host_progress_callback / forward_progress. This needs the stateful StreamableHTTP transport that feat(mcp): support stateless and stateful clients via session-id routing #26857 restored, and it is bounded by the connection/TTL window
• Tasks extension: not implemented yet. It is the stateless successor for long-running work (tasks/get / tasks/update / tasks/cancel), reshaped into an extension in the 2026-07-28 spec RC and gated on the mcp Python SDK v2 line; tracked in LIT-3784

The site docs tree is not present in this branch, so this lands as a code-adjacent README rather than a Docusaurus page; the customer-facing docs page should be added wherever that site builds from

https://claude.ai/code/session_01KDdQ8YqNVM3Hh4a92QBhfq

---

Generated by Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[devin-ai-integration]

🚅 Hi, thanks for the PR! I'm Agent Shin, the automated triage bot for this repository. What's this and why am I getting it?

I read the description against our contribution rubric. Here's how it lined up:

What you got right:

• ✅ Clear problem description
• ✅ Expected vs. actual behavior

What's still missing:

• linked GitHub issue or clearly related issue reference
• end-to-end QA proof (screenshot, video, or real commands with output)

The PR has a clear problem description and explains current vs. future behavior, but it does not link a GitHub issue and provides no end-to-end proof. The only artifact mentioned is a docs file path, which is not QA evidence.

If the description isn't updated in the next 24 hours, I'll auto-close this PR. That's not us saying we don't care about the change; we want the open-PR list to mirror what a maintainer can act on right now, so contributors don't get lost in a backlog. A closed PR is a soft "park this for later," not a rejection. Take your time; everything below still works after the close.

During the grace period: just update the PR description with the missing pieces. No need to ping me; I'll re-check on the next sweep and skip the auto-close if it now passes. See what counts as QA proof for the full rubric (a linked issue alone isn't enough; it covers context, not proof).

If the PR does get auto-closed in 24 hours, you still have easy recovery paths:

• Comment @agent-shin reconsider after updating the description. I'll re-evaluate and reopen the PR if it now passes.
• Comment @greptileai to request a fresh Greptile review; that still works even after the PR is closed, and a stronger score is one of the signals that lifts the PR back into the queue. So a low Greptile score isn't a blocker either.

Internal BerriAI contributors: this rubric doesn't apply to you; ping a maintainer.

(I'm an LLM, so I'm not infallible. If you think I got this wrong, ping a maintainer; they'll override me.)