[rociiu]

Summary

Adds optional remote MCP support. The owner connects remote MCP servers in Settings → Integrations and chooses which of their tools Talorys may use in chat. Nothing changes when no server is configured.

• Transport and auth: Streamable HTTP only. Authentication is none, a bearer token, or OAuth sign-in (authorization code + PKCE, dynamic client registration, automatic refresh).
• Tools: New tools start off. An enabled tool either asks for approval on every call (the default; the card shows server, host and exact arguments) or runs without asking (the owner trusts it as read-only). Server annotations are shown, never trusted.
• Same pipeline as built-in tools: MCP tools are adapted into the existing ToolDefinition shape, so validation, the call budget, per-tool caps, duplicate detection and approvals all apply. Built-in tools come first and the mcp_ prefix is reserved.
• Approvals: bound to the exact arguments and the tool's permission state. A call whose outcome is unknown is reported as "may or may not have run" and is never retried.
• Changes on the server: a changed tool definition hides the tool until it is reviewed again.
• Scheduled routines never get MCP tools.

Security

• /api/mcp is owner-session + CSRF only; access tokens are refused, and the agent can't manage servers.
• Bearer tokens and OAuth state are AES-256-GCM encrypted under the new MCP_CREDENTIAL_KEY secret (the installer adds it; update adds it to older installs). They are never returned, logged, sent to the model or exported.
• Endpoints must be public HTTPS hosts. Private, loopback, metadata and reserved addresses are refused, both as literals and as DNS answers (DNS-over-HTTPS). Redirects are refused, and requests stay on the server's origin (OAuth may also reach a vetted authorization server, which never receives the access token).
• Limits: timeouts, 2 MB responses, 8,000-character results for the model, schema size/depth checks, and up to 20 enabled tools (TALORYS_MCP_MAX_TOOLS). TALORYS_MCP=off turns the feature off.
• Backups carry server name, URL and auth type only; imported servers arrive turned off.

Design note

This uses @modelcontextprotocol/client through a guarded fetch, not the Agents SDK's MCPClientManager. That manager stores transport headers (where a bearer token goes) in plain text in cf_agents_mcp_servers and restores connections on wake with its own fetch, which would bypass the checks above. The OAuth callback is the SPA page /settings/mcp-oauth, which posts to /api/mcp/oauth/callback with the owner's session: the SameSite=Strict cookie isn't sent on the cross-site redirect. This works for both the Pages deployment and the one-Worker deployment.

Upgrading

Migration 12 adds tal_mcp_servers, tal_mcp_tools and a result column on pending actions. Run npx create-talorys@latest update to add MCP_CREDENTIAL_KEY.

Testing

• npm run lint, npm run typecheck, npm run build: clean.
• npm test: agent 713, shared 25, web 28, installer 66, all passing. Coverage includes a real official-SDK Streamable HTTP server and a mock OAuth authorization server.
• Checked end to end in the dev stack against local official-SDK servers: bearer and OAuth connections, an auto-run tool call, an approved call (run exactly once), and the Integrations page at phone width in light mode.
• Not run: the Playwright e2e suite. Its browser binary isn't installed on the machine this was built on.

Docs: docs/mcp.md, plus README, security, architecture, deployment and troubleshooting updates.

🤖 Generated with Claude Code