Skip to content

docs: add an authenticated Streamable HTTP MCP example - #1009

Open
louisss1016 wants to merge 2 commits into
modelscope:mainfrom
louisss1016:docs/mcp-authenticated-streamable-http
Open

louisss1016 wants to merge 2 commits into
modelscope:mainfrom
louisss1016:docs/mcp-authenticated-streamable-http

Conversation

@louisss1016

Copy link
Copy Markdown

Change Summary

Adds an authenticated Streamable HTTP example to both the Chinese and English Tools pages, closing the gap where only an unauthenticated sse example was shown.

The example stays generic — a placeholder host, no external service, no new SDK dependency, no new transport implementation. It only uses the existing mcpServers / headers / include surface.

Each page gets the same three points, in the same order:

  1. Streamable HTTP is the default transport. type only switches the transport for sse and websocket; everything else, including omitting type, goes through Streamable HTTP.
  2. Values in yaml are literal. There is no environment-variable interpolation in the config layer, so ${VAR} is not substituted. Rather than implying otherwise, the example shows reading os.environ in Python and assembling headers there, and says explicitly that a real token should not go into a config file or version control.
  3. headers does not apply to websocket, and the stdio env (passed to the child process) is unrelated to a remote headers (an HTTP request header). Both are easy to conflate and fail silently.

Also documents that include and exclude are mutually exclusive.

Related issue number

Ref #1003 — that issue asks whether a generic placeholder example or a disclosed third-party service example is preferred. This PR implements the generic option, which the issue itself offers as an acceptable alternative. Happy to rework it if maintainers prefer the other direction, and happy to yield to the issue author.

Verification

Docs-only; no runtime behaviour changed. Every claim was checked against source at a56afcc:

  • ms_agent/tools/mcp_client.py — _open_transport special-cases only sse and websocket, everything else falls through to streamablehttp_client; headers= is passed for Streamable HTTP and SSE, and the websocket branch calls websocket_client(url) only.
  • ms_agent/config/config.py — convert_mcp_servers_to_json does deepcopy(server_config) with no key allowlist, so headers / include written under a server in yaml reach the client verbatim.
  • No register_resolver or oc.env anywhere in the repo, which is why ${VAR} interpolation is documented as unsupported rather than assumed.
  • _plan_server asserts Set either include or exclude in tools config., the source of the mutual-exclusivity note.
  • The Python snippet mirrors tests/tools/test_mcp_client.py, which is where MCPClient({'mcpServers': {...}}) and async with MCPClient(...) as ... are already exercised.

Checklist

  • The pull request title is a good summary of the changes - it will be used in the changelog
  • Unit tests for the changes exist — N/A, docs only; no code path is touched
  • Run pre-commit install and pre-commit run --all-files before git commit, and passed lint check — not run locally: this sandbox has no PyPI access, so pre-commit and pytest cannot be installed. The two relevant hooks (trailing-whitespace, end-of-file-fixer, plus mixed-line-ending --fix=lf) were checked by hand: no trailing whitespace, LF endings, no tabs, trailing newline present on both files. lint.yaml runs pre-commit run --from-ref, i.e. changed files only, so unrelated files cannot affect this PR.
  • Documentation reflects the changes where applicable — this PR is documentation, and the zh/en pages were updated together to keep them in parity.

Note: drafted with AI assistance. The source claims above were each read from the code rather than assumed, but the local test/lint run could not be performed here.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant