Skip to content

[Agents] Restructure tools and MCP pages, rename File system to Workspace - #35056

Open
mattzcarey wants to merge 4 commits into
productionfrom
docs/agents-tools-restructure
Open

mattzcarey wants to merge 4 commits into
productionfrom
docs/agents-tools-restructure

Conversation

@mattzcarey

@mattzcarey mattzcarey commented Nov 9, 2026 •

Copy link
Copy Markdown
Member

Renames the File system page to Workspace (/agents/tools/workspace/), adds a tools-and-adapters table to the Tools index, and shows each tool with Think as well as Pi, the AI SDK, and TanStack AI.

  • tools/filesystem becomes tools/workspace, and the MPP page moves from tools/payments/mpp-charge-for-http-content into tools/payments/mpp/. Both have redirects, and links across the Agents docs point to the new paths.
  • The Workspace page gains sections on the shell and container backends, Git, mounts, assets, and Artifacts, on top of @cloudflare/computer 0.10 (CodemodeBackend, codemode:* host modules).
  • Web search, web fetch, browser, and AI Search show a Think example, and AI Search shows a Pi ToolRegistration built with @earendil-works/pi-schema.
  • The MCP client docs follow agents main after fix(mcp): re-authorization and connection failures for the MCP client agents#2782 and Improve forced redirect example #2856: a failed server stays failed until reconnectMcpServer(id) (or connectToServer(id) on a standalone MCPClientManager), refused authorization skips retries, requests that need the user to authorize again throw MCPAuthorizationRequiredError with a link, unknown servers throw MCPConnectionNotFoundError, and transport.headers are stored and sent on restore. The OAuth guide retries with reconnectMcpServer() instead of removing and re-adding the server. MCP package pins move to @modelcontextprotocol/client and /server 2.4.0 and /sdk 1.32.2, and the capability page mentions clientMetadataUrl for Client ID Metadata Documents.
  • The Pi and OpenCode pages gain a short "Connect a workspace" section that points to the Workspace page.
  • The MCP client API page drops its copy of the MCPClientManager reference and points to the MCPClientManager capability page. The MCP tools page lists which harnesses can use MCP tools.
flowchart LR
    core["Tool core"] --> think["Think: getTools()"]
    core --> pi["Pi: ToolRegistration"]
    core --> aisdk["AI SDK: tool()"]
    core --> tanstack["TanStack AI"]
Loading

Code samples typecheck against agents@0.33.0, @cloudflare/computer@0.10.0, and Pi 1.5. Internal links resolve, the pages compile as MDX, and bin/validate-redirects.ts passes. Replaces #34724.

The MCP failure and re-authorization changes ship in agents@0.34.0 (cloudflare/agents#2808).

@github-actions github-actions Bot added product:changelog product:agents Build and deploy AI-powered Agents on Cloudflare that can act autonomously. labels Nov 9, 2026
@cloudflare-docs-bot

cloudflare-docs-bot Bot commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

AI Review

✅ Reviewed 804e6e3 · 2 findings · incremental

👉 Fix in your agent 👈
Fix the following review findings in PR #35056 (https://github.com/cloudflare/cloudflare-docs/pull/35056).

Before making changes, review each finding and present a brief summary table:
- For each finding, state whether you agree, disagree, or need clarification.
- If you disagree, explain why.
- If you need clarification before deciding, ask those questions.
- Then share your plan for which issues to tackle and in what order.

After triaging, follow this order:
1. Post a comment on this PR for any findings you are skipping, with the finding ID and your reasoning.
2. Then commit the fixes for the legitimate findings.

The comment must come before the commit because the next review reads PR comments.

## Style Guide
- S-1af32be9 | src/content/docs/agents/model-context-protocol/apis/client-api.mdx:200 | Semicolon joins two independent clauses
  The bullet uses a semicolon to join two independent clauses (`Server requires OAuth` and `redirect user to authUrl`). The writing-style rules require breaking semicolon-joined independent clauses into separate sentences.
- S-0d39f36b | src/content/docs/agents/tools/web-search.mdx:20 | Contraction `you're` in prose
  The writing style rules require removing contractions from prose. The added line contains `you're` in plain prose, not inside a code block or backtick span.

Style Guide

  • src/content/docs/agents/model-context-protocol/apis/client-api.mdx:200 · Semicolon joins two independent clauses

    The bullet uses a semicolon to join two independent clauses (Server requires OAuth and redirect user to authUrl). The writing-style rules require breaking semicolon-joined independent clauses into separate sentences.

  • src/content/docs/agents/tools/web-search.mdx:20 · Contraction you're in prose

    The writing style rules require removing contractions from prose. The added line contains you're in plain prose, not inside a code block or backtick span.

Commands
  • /review Run a review now.
  • /full-review Review the entire PR diff.
  • /disable-auto-review Stop automatic reviews.
  • /rebase Rebase against production.

@cloudflare-docs-bot

cloudflare-docs-bot Bot commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

Review coverage

✅ All 4 ownership areas are covered.

✅ 4 areas already covered
Area Approved by
Other
1 file changed
/public/__redirects
irvinebroque
Other
1 file changed
/src/components/cf/AgentsPlatformDiagram.astro
irvinebroque
agents
32 files changed
/src/content/docs/agents/
irvinebroque
agents
2 files changed
/src/content/changelog/agents/
irvinebroque
CODEOWNERS mappings for displayed areas (4)
Pattern Owners
/public/__redirects @cloudflare/product-owners, @cloudflare/content-engineering
/src/components/cf/AgentsPlatformDiagram.astro @irvinebroque, @fredkschott, @cloudflare/ai-agents
/src/content/docs/agents/ @irvinebroque, @rita3ko, @cloudflare/ai-agents, @cloudflare/dev-plat-leads, @cloudflare/product-owners
/src/content/changelog/agents/ @irvinebroque, @rita3ko, @cloudflare/ai-agents, @cloudflare/dev-plat-leads, @cloudflare/pm-changelogs, @cloudflare/product-owners

@github-actions

github-actions Bot commented Nov 9, 2026

Copy link
Copy Markdown
Contributor

This PR changes current filenames or deletes current files. Make sure you have redirects set up to cover the following paths:

  • /agents/tools/payments/mpp-charge-for-http-content/
  • /agents/tools/filesystem/

@cloudflare-workers-and-pages

cloudflare-workers-and-pages Bot commented Nov 9, 2026 •

Copy link
Copy Markdown

🚀 Deploying Preview to Cloudflare 🚀

Preview URL: https://docs-agents-tools-restructure.previews.developers.cloudflare.com (commit dec0f20)

This URL reflects your latest Preview deployment

Preview Deployments by commit

Status Deployment URL Commit Updated (UTC) See this deployment's details
  • Build: Failed ❌

View logs ↗
804e6e3 2026-11-10T12:07:02.779Z View logs ↗
  • Build: Success ✅
  • Deployment: Success ✅

View logs ↗
https://119f8b03.previews.developers.cloudflare.com dec0f20 2026-11-09T19:44:23.266Z Visit the dashboard ↗
  • Build: In progress 🔵

View logs ↗
01617ec 2026-11-09T19:20:43.914Z View logs ↗

@github-actions

github-actions Bot commented Nov 9, 2026

Copy link
Copy Markdown
Contributor

Worker Preview URL: https://gh-docs-agents-tools-restructure.previews.developers.cloudflare.com
Worker Preview Deployment URL: https://b45e7f56.previews.developers.cloudflare.com

Files with changes (up to 15)

Original Link Updated Link
https://developers.cloudflare.com/agents/tools/workspace/ https://gh-docs-agents-tools-restructure.previews.developers.cloudflare.com/agents/tools/workspace/
https://developers.cloudflare.com/agents/model-context-protocol/apis/client-api/ https://gh-docs-agents-tools-restructure.previews.developers.cloudflare.com/agents/model-context-protocol/apis/client-api/
https://developers.cloudflare.com/agents/tools/ai-search/ https://gh-docs-agents-tools-restructure.previews.developers.cloudflare.com/agents/tools/ai-search/
https://developers.cloudflare.com/agents/tools/mcp/ https://gh-docs-agents-tools-restructure.previews.developers.cloudflare.com/agents/tools/mcp/
https://developers.cloudflare.com/agents/tools/browser/ https://gh-docs-agents-tools-restructure.previews.developers.cloudflare.com/agents/tools/browser/
https://developers.cloudflare.com/agents/tools/web-search/ https://gh-docs-agents-tools-restructure.previews.developers.cloudflare.com/agents/tools/web-search/
https://developers.cloudflare.com/agents/tools/ https://gh-docs-agents-tools-restructure.previews.developers.cloudflare.com/agents/tools/
https://developers.cloudflare.com/agents/tools/web-fetch/ https://gh-docs-agents-tools-restructure.previews.developers.cloudflare.com/agents/tools/web-fetch/
https://developers.cloudflare.com/agents/model-context-protocol/ https://gh-docs-agents-tools-restructure.previews.developers.cloudflare.com/agents/model-context-protocol/
https://developers.cloudflare.com/agents/tools/payments/mpp/charge-for-http-content/ https://gh-docs-agents-tools-restructure.previews.developers.cloudflare.com/agents/tools/payments/mpp/charge-for-http-content/
https://developers.cloudflare.com/agents/harnesses/pi/ https://gh-docs-agents-tools-restructure.previews.developers.cloudflare.com/agents/harnesses/pi/
https://developers.cloudflare.com/changelog/post/2026-10-26-computer-durable-javascript/ https://gh-docs-agents-tools-restructure.previews.developers.cloudflare.com/changelog/post/2026-10-26-computer-durable-javascript/
https://developers.cloudflare.com/agents/getting-started/quick-start/ https://gh-docs-agents-tools-restructure.previews.developers.cloudflare.com/agents/getting-started/quick-start/
https://developers.cloudflare.com/agents/harnesses/opencode/ https://gh-docs-agents-tools-restructure.previews.developers.cloudflare.com/agents/harnesses/opencode/
https://developers.cloudflare.com/agents/tools/payments/x402/pay-with-tool-plugins/ https://gh-docs-agents-tools-restructure.previews.developers.cloudflare.com/agents/tools/payments/x402/pay-with-tool-plugins/


## Connect a workspace

OpenCode's Workers profile has no local filesystem or process, so its `read`, `write`, `edit`, `patch`, `glob`, `grep`, and `shell` tools cannot run in a Durable Object. To give OpenCode files that survive restarts, register the tools of a [Cloudflare Computer](/agents/tools/workspace/) `Workspace` through a plugin. The plugin removes OpenCode's local tools and adds the workspace tools from `createPiTools()`. Refer to [Workspace tools with OpenCode](/agents/tools/workspace/#opencode) for the plugin.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

workers profile makes so sense. reword this without using jargon that makes. no sense

@github-actions

Copy link
Copy Markdown
Contributor

CI run failed: build logs

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

Labels

product:agents Build and deploy AI-powered Agents on Cloudflare that can act autonomously. product:changelog size/xl

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants