Skip to content

armgit / eve

Public Imported from GitHub
0

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.mdx
index 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 |