Title: ci: deploy docs via GitHub Actions to py.sdk.modelcontextprotocol.io by maxisbey · Pull Request #2632 · modelcontextprotocol/python-sdk · GitHub
Open Graph Title: ci: deploy docs via GitHub Actions to py.sdk.modelcontextprotocol.io by maxisbey · Pull Request #2632 · modelcontextprotocol/python-sdk
X Title: ci: deploy docs via GitHub Actions to py.sdk.modelcontextprotocol.io by maxisbey · Pull Request #2632 · modelcontextprotocol/python-sdk
Description: Motivation and Context Fixes #2614. The Python SDK docs link on https://modelcontextprotocol.io/docs/sdk points to https://py.sdk.modelcontextprotocol.io/, which returns 404. Every other SDK serves correctly at its *.sdk.modelcontextprotocol.io domain. The DNS is already fully configured in modelcontextprotocol/dns (py.sdk CNAME → modelcontextprotocol.github.io, plus the GitHub Pages domain verification TXT records) and resolves correctly. The 404 is entirely a Pages-side gap: no Pages site claims the custom domain (gh api repos/modelcontextprotocol/python-sdk/pages shows cname: null). The root cause is the deployment mechanism. Docs are published with mkdocs gh-deploy --force, which force-pushes the built site to the gh-pages branch. With branch-based Pages, a custom domain only works if a CNAME file is present in that branch — and a force-push overwrites it on every publish. This is a known wart of the gh-deploy model. This PR migrates to the GitHub Actions Pages artifact pipeline (configure-pages → upload-pages-artifact → deploy-pages), which is GitHub's recommended modern model and what the TypeScript SDK already uses: The custom domain becomes a persistent repository Pages setting, not a file that gets overwritten — it survives every deploy. Drops contents: write (a bot pushing commits) in favour of scoped, short-lived pages: write + id-token: write (OIDC). No generated HTML accumulating in a gh-pages branch; atomic deploys with a real github-pages environment. Deploys continuously on push to main instead of only via manual workflow_dispatch, so docs no longer drift from main (workflow_dispatch is retained as a manual trigger). site_url is also updated to https://py.sdk.modelcontextprotocol.io/ so canonical links and sitemap.xml match the published domain. This subsumes and supersedes #2615 (which changed only site_url — necessary but not sufficient on its own). Prior art: this mirrors the TypeScript SDK's docs deployment (modelcontextprotocol/typescript-sdk#1109 introduced GitHub Pages deployment; modelcontextprotocol/typescript-sdk#1584 moved it to the artifact-based deploy-pages model used here). Maintainer action required after merge The workflow change alone does not flip the Pages mechanism — a repo admin must do the following one-time settings change (the manual-publish path required a maintainer too, so this adds no new gate). Recommended order to avoid a broken intermediate state: Settings → Pages → Source: GitHub Actions (switches build_type from legacy to workflow). Merge this PR (or run the workflow via workflow_dispatch) and confirm the first Actions deployment succeeds. Settings → Pages → Custom domain: py.sdk.modelcontextprotocol.io, Save. (Equivalently: gh api -X PUT repos/modelcontextprotocol/python-sdk/pages -f cname=py.sdk.modelcontextprotocol.io.) DNS is already verified, so this is near-instant. Once the certificate is issued, tick Enforce HTTPS. No DNS changes are needed. After step 3 the custom domain persists across all future deploys. The old modelcontextprotocol.github.io/python-sdk/ path keeps working — GitHub 301-redirects it to the custom domain. Verify: gh api repos/modelcontextprotocol/python-sdk/pages --jq '{build_type,cname,https_enforced}' # expect: {"build_type":"workflow","cname":"py.sdk.modelcontextprotocol.io","https_enforced":true} curl -sI https://py.sdk.modelcontextprotocol.io/ # expect HTTP/2 200 The stale gh-pages branch can be deleted once the custom domain is confirmed serving. How Has This Been Tested? uv run --frozen --no-sync mkdocs build was run locally: it builds in strict mode, outputs to site/ (matching the artifact path:), and the generated index.html canonical tag and sitemap.xml correctly use https://py.sdk.modelcontextprotocol.io/. The Pages source/custom-domain toggle is a repo setting and is covered in the maintainer checklist above. Breaking Changes No. User-facing docs URLs are unchanged (the new domain is where the docs were always meant to be served; the old github.io path redirects). Types of changes Bug fix (non-breaking change which fixes an issue) New feature (non-breaking change which adds functionality) Breaking change (fix or feature that would cause existing functionality to change) Documentation update Checklist I have read the MCP Documentation My code follows the repository's style guidelines New and existing tests pass locally I have added appropriate error handling I have added or updated documentation as needed Additional context Pages actions are pinned to commit SHAs to match the repository's existing workflow convention. AI Disclaimer
Open Graph Description: Motivation and Context Fixes #2614. The Python SDK docs link on https://modelcontextprotocol.io/docs/sdk points to https://py.sdk.modelcontextprotocol.io/, which returns 404. Every other SDK serves...
X Description: Motivation and Context Fixes #2614. The Python SDK docs link on https://modelcontextprotocol.io/docs/sdk points to https://py.sdk.modelcontextprotocol.io/, which returns 404. Every other SDK serves...
Opengraph URL: https://github.com/modelcontextprotocol/python-sdk/pull/2632
X: @github
Domain: github.com
| react-profiling | 0 |
| react-import-map | react,react-dom,react-dom/client,react-dom/profiling,react-is,react/compiler-runtime,react/jsx-dev-runtime,react/jsx-runtime,scheduler@b8488ee2c322 |
| route-pattern | /:user_id/:repository/pull/:id/files(.:format) |
| route-controller | pull_requests |
| route-action | files |
| fetch-nonce | v2:92a03208-ff63-56c0-7791-4523e2a41821 |
| current-catalog-service-hash | ae870bc5e265a340912cde392f23dad3671a0a881730ffdadd82f2f57d81641b |
| request-id | DF08:3201B9:CF547:1138B6:6AFD2BFD |
| html-safe-nonce | 6306bb35bbdcf20da842794587df5a76562bf389bb56d3ad32d481067b64ccbc |
| visitor-payload | eyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiJERjA4OjMyMDFCOTpDRjU0NzoxMTM4QjY6NkFGRDJCRkQiLCJ2aXNpdG9yX2lkIjoiNTE1NjQ3NjY3NTgyMjUyOTUzMyIsInJlZ2lvbl9lZGdlIjoiaWFkIiwicmVnaW9uX3JlbmRlciI6ImlhZCJ9 |
| visitor-hmac | 7826718ab1edd0a97b4fa5f9e77fb58355cbfb16cd45945f414bad8206032b26 |
| hovercard-subject-tag | pull_request:3701896266 |
| github-keyboard-shortcuts | repository,pull-request-list,pull-request-conversation,pull-request-files-changed,copilot |
| google-site-verification | Apib7-x98H0j5cPqHWwSMm6dNU4GmODRoqxLiDzdx9I |
| octolytics-url | https://collector.github.com/github/collect |
| analytics-location | / |
| fb:app_id | 1401488693436528 |
| apple-itunes-app | app-id=1477376905, app-argument=https://github.com/modelcontextprotocol/python-sdk/pull/2632/files |
| twitter:image | https://avatars.githubusercontent.com/u/224885523?s=400&v=4 |
| twitter:card | summary_large_image |
| og:image | https://avatars.githubusercontent.com/u/224885523?s=400&v=4 |
| og:image:alt | Motivation and Context Fixes #2614. The Python SDK docs link on https://modelcontextprotocol.io/docs/sdk points to https://py.sdk.modelcontextprotocol.io/, which returns 404. Every other SDK serves... |
| og:site_name | GitHub |
| og:type | object |
| hostname | github.com |
| expected-hostname | github.com |
| None | 065128366c233a9d57ff68ab6c96e25b99dd1b0ab70d23b70873d3dd6b5e4f19 |
| turbo-cache-control | no-preview |
| diff-view | unified |
| go-import | github.com/modelcontextprotocol/python-sdk git https://github.com/modelcontextprotocol/python-sdk.git |
| octolytics-dimension-user_id | 182288589 |
| octolytics-dimension-user_login | modelcontextprotocol |
| octolytics-dimension-repository_id | 862584018 |
| octolytics-dimension-repository_nwo | modelcontextprotocol/python-sdk |
| octolytics-dimension-repository_public | true |
| octolytics-dimension-repository_is_fork | false |
| octolytics-dimension-repository_network_root_id | 862584018 |
| octolytics-dimension-repository_network_root_nwo | modelcontextprotocol/python-sdk |
| turbo-body-classes | logged-out env-production page-responsive full-width |
| disable-turbo | true |
| browser-stats-url | https://api.github.com/_private/browser/stats |
| browser-errors-url | https://api.github.com/_private/browser/errors |
| release | 941021edf0c2ec58298f4a2c8f27ae507d129c92 |
| ui-target | full |
| theme-color | #1e2327 |
| color-scheme | light dark |
Links:
Viewport: width=device-width