mcp-tools

name	mcp-tools
description	Use when adding, changing, or reviewing MCP servers, MCP tools, session tools, tool registration, Cloudflare AI Search sources, AI Search ingestion resources, or the AI Search MCP server in this repo.

MCP Tools

Use this skill when working on MCP/tool behavior in this repo. Start from the shared contracts and existing registration points, then wire the runtime. Avoid adding one-off tool code when an existing tool surface or registry can express the behavior.

General MCP And Tool Pattern

• Shared session tool contracts live in packages/shared/src/session-tools.ts.
• Session MCP selection, headers, and internal server config live in packages/api/src/server/background/session/mcp-config.ts.
• Internal MCP server entrypoints live under packages/api/src/server/mcp/.
• Isolate/local session tools live under packages/api/src/server/background/isolate/.
• Effect API schemas and routes live under packages/api/src/http/ and packages/api/src/server/effect/.

When adding or changing a tool:

1. Put user/session-visible identifiers in the shared package first.
2. Normalize and validate user-selected tools at the boundary where tools enter session state.
3. Register MCP tools with stable, action-oriented names and descriptions that state what the tool returns.
4. Keep authorization and selection outside the runtime. The MCP server should only register tools attached to the current session.
5. Dispatch from the tool registration into a shared runtime function. Do not fork source-specific logic into separate MCP servers unless the protocol or auth model is actually different.
6. Preserve isolate behavior. Docs-only sessions must not require an attached repository.
7. Update tests at the contract, MCP config, runtime, and Worker route levels when the public tool surface changes.

Internal MCP Rules

• Use one MCP server when tools share auth, transport, and runtime dependencies.
• Expose each selected capability as its own MCP tool in tools/list.
• Keep custom MCP servers separate from predefined internal tools. Reject custom names that collide with reserved internal server names.
• Keep follow-up streamable HTTP requests working by preserving header-based source selection and the D1 session fallback via x-c0-session-id.
• Keep tool input schemas narrow. Prefer query: z.string().min(1) for search tools unless the caller genuinely needs more control.

AI Search Source Pattern

AI Search resources in this repo use a common shape:

docs in R2 -> Cloudflare AI Search vector index -> shared MCP runtime -> source-specific MCP tools

For a new AI Search-backed document source:

1. Create or adopt the R2 + AI Search resource with createAiSearchR2 in apps/api/infra/resources.ts.
2. Add the source id to the aiSearchSourceIds map returned by createAgentResources.
3. Bind the map through AI_SEARCH_SOURCE_IDS_JSON in apps/api/infra/index.ts.
4. Add public source metadata in packages/shared/src/session-tools.ts.
5. Add runtime config in packages/api/src/server/mcp/ai-search-sources.ts, keeping maxResults explicit and source IDs resolved through the shared map.
6. Register the source in packages/api/src/server/mcp/ai-search-server.ts.
7. Run the MCP integration tests and update any session UI source picker affected by the new source.

Each AI Search source should expose two MCP tools:

• search_*: calls the shared runtime with mode: "search" and returns retrieval-only source results.
• ask_*: calls the shared runtime with mode: "aiSearch" and returns a generated answer plus retrieved sources.

The runtime belongs in packages/api/src/server/mcp/ai-search-runtime.ts. It should accept the source id, query, runtime context, and required mode, then call the configured AI Search binding. Do not add default-mode or old-env fallbacks; source differences should come from registry metadata and runtime config.

Runtime-Configured AI Search Sources

AI Search sources are created and maintained through the runtime registry. Do not hardcode source ids, labels, domains, or document collections in this skill; each deployment chooses its own sources.

Validation

Run focused checks while iterating:

nub exec vitest run tests/integration/ai-search-mcp.test.ts tests/integration/session-mcp-config.test.ts

Before handoff, run the repo-root checks required by AGENTS.md:

nub run typecheck
nub run lint
nub run format