The Open Framework for Building Agents
docs(connections): document gating MCP tools by name or input (#329)
Ben Sabic182bc5b4cf4b
diff --git a/docs/connections/mcp.mdx b/docs/connections/mcp.mdxindex 45331a431..00a5d85d9 100644--- a/docs/connections/mcp.mdx+++ b/docs/connections/mcp.mdx@@ -141,6 +141,51 @@ export default defineMcpClientConnection({`once()` asks the first time in a session, `always()` asks on every tool call, and `never()` allows calls without approval. Authorization and approval work together: eve records approval before an OAuth park, then resumes without asking again for the same approved call.+The `once()`, `always()`, and `never()` helpers from `eve/tools/approval` gate every tool the connection serves the same way. See [Connections](/docs/connections#per-connection-approval) for those, and [Human-in-the-loop](/docs/human-in-the-loop) for the full pause-and-resume contract.++### Gate specific tools by name or input++A remote MCP server usually mixes read tools with destructive or publishing ones, so a blanket `always()` would prompt on every harmless call. Pass a custom policy instead — the same [`Approval`](/docs/human-in-the-loop#approvals) shape authored tools use — to gate only the calls that matter. The policy receives `{ session, toolName, toolInput, approvedTools }` and returns an approval status, synchronously or as a promise.++This connection always gates deletes, gates a publish only when the call actually schedules a post, and lets everything else through:++```ts title="agent/connections/social.ts"+import { defineMcpClientConnection } from "eve/connections";++// Bare tool names whose effects are irreversible — always gate these.+const DELETE_TOOLS = ["delete_draft", "delete_thread"];+// Tools that can publish — gate only when the call schedules a post.+const PUBLISH_TOOLS = ["create_draft", "edit_draft"];++// Read `requestBody.publish_at` without trusting the input's shape.+const publishesNow = (input: unknown): boolean => {+ const body = (input as { requestBody?: { publish_at?: unknown } })?.requestBody;+ return typeof body?.publish_at === "string" && body.publish_at.length > 0;+};++export default defineMcpClientConnection({+ url: "https://mcp.example.com/mcp",+ description: "Social publishing: draft, schedule, and manage posts.",+ auth: { getToken: async () => ({ token: process.env.SOCIAL_API_KEY! }) },+ approval: ({ toolName, toolInput }) => {+ if (DELETE_TOOLS.some((t) => toolName.includes(t))) return "user-approval";+ if (PUBLISH_TOOLS.some((t) => toolName.includes(t))) {+ return publishesNow(toolInput) ? "user-approval" : "not-applicable";+ }+ return "not-applicable";+ },+});+```++Two details are specific to connection tools:++- **`toolName` arrives qualified**, not as the bare remote name. An MCP tool surfaces to the policy as `<connection>__<tool>` (e.g. `social__delete_draft`), so match the bare tool name with `.includes()` or `.endsWith()` rather than `===`.+- **`toolInput` is the raw input the model produced**, typed as `Record<string, unknown> | undefined`. With an authored tool you define the `inputSchema`, so its approval policy gets input typed and checked against your schema; a connection tool's schema is published by the remote MCP server, not you, so the shape is one you neither own nor can rely on. It is also `undefined` whenever the model's input isn't an object. Read nested fields defensively — as `publishesNow` does — instead of trusting the shape.++Return `"user-approval"` (or `true`) to pause for a person and `"not-applicable"` (or `false`) to run without a prompt; return `"approved"` or `"denied"` to decide automatically without involving anyone.++[Human-in-the-loop](/docs/human-in-the-loop#approvals) covers the full set of statuses, how `approvedTools` and `session.auth` factor in, and how a gated call pauses and resumes durably.+## Troubleshooting| Symptom | Check |