Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

Support application-provided MCP tool arguments (#1809)

Allen Zhou0dbe7ef49ce3
diff --git a/.changeset/clean-spoons-call.md b/.changeset/clean-spoons-call.md
new file mode 100644
index 000000000..25cc23c49
--- /dev/null
+++ b/.changeset/clean-spoons-call.md
@@ -0,0 +1,5 @@
+---
+"eve": patch
+---
+
+Add `toolCall.providedArguments` to MCP and OpenAPI connections so applications can hide and supply application-owned arguments on every remote tool call.
diff --git a/docs/connections/mcp.mdx b/docs/connections/mcp.mdx
index 00a5d85d9..9338cbc66 100644
--- a/docs/connections/mcp.mdx
+++ b/docs/connections/mcp.mdx
@@ -89,6 +89,34 @@ export default defineMcpClientConnection({
`auth` and `headers` can also be functions that receive the active session context. Use that when credentials, tenants, or routing depend on the caller.
+## Application-provided tool arguments
+
+Some MCP servers require arguments that belong to the application rather than the model. For example, UCP servers expect the agent profile in `arguments.meta` on every tool call. Configure those values with `toolCall.providedArguments`:
+
+```ts title="agent/connections/storefront.ts"
+import { defineMcpClientConnection } from "eve/connections";
+
+const profileUrl = "https://agent.example.com/.well-known/ucp";
+
+export default defineMcpClientConnection({
+ url: "https://store.example.com/api/ucp/mcp",
+ description: "Storefront catalog, carts, checkouts, and orders.",
+ toolCall: {
+ providedArguments: {
+ meta: ({ session }) => ({
+ "ucp-agent": {
+ profile: `${profileUrl}?session=${encodeURIComponent(session.id)}`,
+ },
+ }),
+ },
+ },
+});
+```
+
+Values may be JSON values, promises, or callbacks. Callbacks receive the active session context plus the bare remote `toolName`.
+
+eve treats configured keys as application-owned: it removes them from every remote tool's model-facing input schema and adds their resolved values immediately before execution. They apply to every tool call on the connection and replace any conflicting model value. Approval policies continue to receive only the model-authored input.
+
## No auth
Omit `auth` and `headers` only for intentionally public or local-only servers:
@@ -193,7 +221,7 @@ Return `"user-approval"` (or `true`) to pause for a person and `"not-applicable"
| `principal_required` | A user-scoped `connect("...")` ran without an authenticated user. Return `principalType: "user"` from route auth, or use app-scoped auth. |
| The model does not find the remote tool | Improve the connection `description`, then check `tools.allow` / `tools.block`. |
| OAuth works locally but fails after deploy | Attach the Connect connector to the deployed Vercel project and verify the UID in `connect("...")`. |
-| The server rejects requests | Confirm the MCP URL, transport support, auth scheme, and any required headers. |
+| The server rejects requests | Confirm the MCP URL, transport support, auth scheme, required headers, and application-provided arguments. |
## What to read next
diff --git a/docs/connections/openapi.mdx b/docs/connections/openapi.mdx
index 98e4d373e..861356556 100644
--- a/docs/connections/openapi.mdx
+++ b/docs/connections/openapi.mdx
@@ -117,6 +117,30 @@ export default defineOpenAPIConnection({
`auth` and `headers` can also be functions that receive the active session context. Use that when credentials, tenants, or routing depend on the caller.
+## Application-provided operation arguments
+
+Some APIs declare operation parameters that should come from the application rather than the model, such as a tenant or organization ID. Configure those values with `toolCall.providedArguments`:
+
+```ts title="agent/connections/crm.ts"
+import { defineOpenAPIConnection } from "eve/connections";
+
+export default defineOpenAPIConnection({
+ spec: "https://api.example.com/openapi.json",
+ description: "CRM accounts, contacts, and opportunities.",
+ toolCall: {
+ providedArguments: {
+ tenantId: ({ session }) => String(session.auth.current?.attributes.tenant ?? ""),
+ },
+ },
+});
+```
+
+Values may be JSON values, promises, or callbacks. Callbacks receive the active session context plus the bare operation `toolName`.
+
+eve removes configured keys from every operation's model-facing input schema and adds their resolved values immediately before constructing the HTTP request. Values apply to every operation on the connection and replace any conflicting model value. The keys correspond to the generated top-level operation inputs: path, query, header, and cookie parameter names, plus `body` for a request body.
+
+Use `headers` for transport-wide headers that are not operation inputs. Use `providedArguments` when the OpenAPI document declares the value as an operation parameter and it should remain outside model control. Approval policies continue to receive only the model-authored input.
+
## Operation filters
Most OpenAPI specs describe far more than the model should use. Narrow generated tools with exactly one of `operations.allow` or `operations.block`:
diff --git a/packages/eve/extension-contracts/compatibility/connection/v2.ts b/packages/eve/extension-contracts/compatibility/connection/v2.ts
new file mode 100644
index 000000000..3c7e0ec2e
--- /dev/null
+++ b/packages/eve/extension-contracts/compatibility/connection/v2.ts
@@ -0,0 +1,8 @@
+import { defineMcpClientConnection } from "#public/connections/index.js";
+
+export default defineMcpClientConnection({
+ url: "https://example.com/mcp",
+ description: "Example MCP service",
+ headers: { "X-Api-Key": "example" },
+ tools: { allow: ["search"] },
+});
diff --git a/packages/eve/extension-contracts/compatibility/tool/v8.ts b/packages/eve/extension-contracts/compatibility/tool/v8.ts
new file mode 100644
index 000000000..35c4c7be1
--- /dev/null
+++ b/packages/eve/extension-contracts/compatibility/tool/v8.ts
@@ -0,0 +1,13 @@
+import { defineTool } from "#public/tools/index.js";
+
+export default defineTool({
+ description: "Look up a report.",
+ inputSchema: {
+ type: "object",
+ properties: { reportId: { type: "string" } },
+ required: ["reportId"],
+ },
+ execute(input) {
+ return { reportId: input.reportId };
+ },
+});
diff --git a/packages/eve/extension-contracts/reports/connection/v3.json b/packages/eve/extension-contracts/reports/connection/v3.json
new file mode 100644
index 000000000..bf59421e4
--- /dev/null
+++ b/packages/eve/extension-contracts/reports/connection/v3.json
@@ -0,0 +1,15 @@
+{
+ "kind": "eve-extension-capability-contract",
+ "capability": "connection",
+ "epoch": 3,
+ "sha256": "bb909f15ac0503bc97b2cf27d4f5ac1ece2062d322778f4a5ef4e5a3adcac12f",
+ "exports": [
+ "ConnectionAuthorizationFailedError",
+ "ConnectionAuthorizationRequiredError",
+ "defineInteractiveAuthorization",
+ "defineMcpClientConnection",
+ "defineOpenAPIConnection",
+ "isConnectionAuthorizationFailedError",
+ "isConnectionAuthorizationRequiredError"
+ ]
+}
diff --git a/packages/eve/extension-contracts/reports/tool/v9.json b/packages/eve/extension-contracts/reports/tool/v9.json
new file mode 100644
index 000000000..0ed5d108f
--- /dev/null
+++ b/packages/eve/extension-contracts/reports/tool/v9.json
@@ -0,0 +1,22 @@
+{
+ "kind": "eve-extension-capability-contract",
+ "capability": "tool",
+ "epoch": 9,
+ "sha256": "05ba60dd6618fd3207ab8fe16b1d72072f163e2b701a7c1a7adfa60c131045da",
+ "exports": [
+ "defineBashTool",
+ "defineGlobTool",
+ "defineGrepTool",
+ "defineReadFileTool",
+ "defineTool",
+ "defineWriteFileTool",
+ "disableTool",
+ "experimental_workflow",
+ "isDisabledToolSentinel",
+ "isExperimentalWorkflowToolDefinition",
+ "toolOutput",
+ "toolOutputPart",
+ "toolResultFrom",
+ "webSearch"
+ ]
+}
diff --git a/packages/eve/src/compiler/extension-compatibility.ts b/packages/eve/src/compiler/extension-compatibility.ts
index d7061d3a3..771caa464 100644
--- a/packages/eve/src/compiler/extension-compatibility.ts
+++ b/packages/eve/src/compiler/extension-compatibility.ts
@@ -21,9 +21,9 @@ interface ExtensionCapabilityContract {
const EXTENSION_CAPABILITY_CONTRACTS = {
extension: { current: 1, supported: [1], dropped: {} },
- tool: { current: 8, supported: [1, 2, 3, 4, 5, 6, 7, 8], dropped: {} },
+ tool: { current: 9, supported: [1, 2, 3, 4, 5, 6, 7, 8, 9], dropped: {} },
dynamicTool: { current: 10, supported: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10], dropped: {} },
- connection: { current: 2, supported: [1, 2], dropped: {} },
+ connection: { current: 3, supported: [1, 2, 3], dropped: {} },
hook: { current: 8, supported: [1, 2, 3, 4, 5, 6, 7, 8], dropped: {} },
skill: { current: 1, supported: [1], dropped: {} },
dynamicSkill: { current: 7, supported: [1, 2, 3, 4, 5, 6, 7], dropped: {} },
diff --git a/packages/eve/src/internal/authored-definition/connection.test.ts b/packages/eve/src/internal/authored-definition/connection.test.ts
index b6e078543..9b9d65f38 100644
--- a/packages/eve/src/internal/authored-definition/connection.test.ts
+++ b/packages/eve/src/internal/authored-definition/connection.test.ts
@@ -446,6 +446,49 @@ describe("normalizeMcpClientConnectionDefinition", () => {
});
});
+ describe("toolCall.providedArguments validation", () => {
+ it("accepts static, Promise, and function values", () => {
+ const resolver = () => ({ profile: "https://agent.example.com/profile" });
+ const promised = Promise.resolve("request-id");
+ const result = normalizeMcpClientConnectionDefinition(
+ validInput({
+ toolCall: {
+ providedArguments: {
+ meta: resolver,
+ requestId: promised,
+ version: 1,
+ },
+ },
+ }),
+ MSG,
+ );
+
+ expect(result.toolCall?.providedArguments).toEqual({
+ meta: resolver,
+ requestId: promised,
+ version: 1,
+ });
+ });
+
+ it("rejects unknown toolCall fields", () => {
+ expect(() =>
+ normalizeMcpClientConnectionDefinition(
+ validInput({ toolCall: { prepare: () => ({}) } }),
+ MSG,
+ ),
+ ).toThrow(/Unknown key "prepare"/);
+ });
+
+ it("rejects non-JSON static values", () => {
+ expect(() =>
+ normalizeMcpClientConnectionDefinition(
+ validInput({ toolCall: { providedArguments: { meta: new Date() } } }),
+ MSG,
+ ),
+ ).toThrow(/toolCall\.providedArguments\.meta.*JSON-serializable/);
+ });
+ });
+
describe("tools (tool filter) validation", () => {
it("accepts an allow filter", () => {
const result = normalizeMcpClientConnectionDefinition(
diff --git a/packages/eve/src/internal/authored-definition/connection.ts b/packages/eve/src/internal/authored-definition/connection.ts
index 059fe41f6..96f6aae8f 100644
--- a/packages/eve/src/internal/authored-definition/connection.ts
+++ b/packages/eve/src/internal/authored-definition/connection.ts
@@ -1,5 +1,9 @@
import type { McpClientConnectionDefinition } from "#public/definitions/connections/mcp.js";
import type { OpenAPIConnectionDefinition } from "#public/definitions/connections/openapi.js";
+import type {
+ ConnectionToolCallDefinition,
+ ProvidedArgumentsDefinition,
+} from "#public/definitions/connections/tool-call.js";
import type {
ConnectionAuthDefinition,
HeadersDefinition,
@@ -7,12 +11,14 @@ import type {
} from "#runtime/connections/types.js";
import { normalizeAuthorizationSpec } from "#runtime/connections/validate-authorization.js";
import { expectObjectRecord, expectOnlyKnownKeys } from "#internal/authored-module.js";
+import { parseJsonValue } from "#shared/json.js";
const KNOWN_TOP_LEVEL_KEYS = [
"approval",
"auth",
"description",
"headers",
+ "toolCall",
"tools",
"url",
] as const;
@@ -24,6 +30,7 @@ const KNOWN_OPENAPI_TOP_LEVEL_KEYS = [
"headers",
"operations",
"spec",
+ "toolCall",
] as const;
const KNOWN_AUTHORIZATION_KEYS = [
"completeAuthorization",
@@ -42,6 +49,7 @@ const KNOWN_AUTHORIZATION_KEYS = [
// canonical producer.
"vercelConnect",
] as const;
+const KNOWN_TOOL_CALL_KEYS = ["providedArguments"] as const;
/**
* Validates one authored MCP client connection module export at build time
@@ -62,6 +70,7 @@ export function normalizeMcpClientConnectionDefinition(
const authorization = normalizeAuthorization(record, message);
const headers = normalizeHeaders(record, message);
+ const toolCall = normalizeConnectionToolCall(record, message);
const tools = normalizeToolFilter(record, message);
if (authorization !== undefined && headers !== undefined && typeof headers !== "function") {
@@ -84,6 +93,9 @@ export function normalizeMcpClientConnectionDefinition(
if (headers !== undefined) {
result.headers = headers;
}
+ if (toolCall !== undefined) {
+ result.toolCall = toolCall;
+ }
if (tools !== undefined) {
result.tools = tools;
}
@@ -98,6 +110,52 @@ export function normalizeMcpClientConnectionDefinition(
return result;
}
+function normalizeConnectionToolCall(
+ record: Record<string, unknown>,
+ message: string,
+): ConnectionToolCallDefinition | undefined {
+ if (record.toolCall === undefined) {
+ return undefined;
+ }
+
+ const toolCall = expectObjectRecord(
+ record.toolCall,
+ `${message} The "toolCall" field must be a plain object.`,
+ );
+ expectOnlyKnownKeys(toolCall, KNOWN_TOOL_CALL_KEYS, `${message} The "toolCall" field`);
+
+ if (toolCall.providedArguments === undefined) {
+ return {};
+ }
+
+ const providedArguments = expectObjectRecord(
+ toolCall.providedArguments,
+ `${message} The "toolCall.providedArguments" field must be a plain object.`,
+ );
+
+ for (const [key, value] of Object.entries(providedArguments)) {
+ if (typeof value === "function") {
+ continue;
+ }
+ if (
+ typeof value === "object" &&
+ value !== null &&
+ typeof (value as { then?: unknown }).then === "function"
+ ) {
+ continue;
+ }
+ try {
+ parseJsonValue(value);
+ } catch {
+ throw new Error(
+ `${message} The "toolCall.providedArguments.${key}" value must be JSON-serializable, a Promise, or a function.`,
+ );
+ }
+ }
+
+ return { providedArguments: providedArguments as ProvidedArgumentsDefinition };
+}
+
/**
* Validates one authored OpenAPI connection module export at build time
* and returns the public definition type. Mirrors
@@ -119,6 +177,7 @@ export function normalizeOpenApiConnectionDefinition(
const authorization = normalizeAuthorization(record, message);
const headers = normalizeHeaders(record, message);
const operations = normalizeFilterField(record, "operations", message);
+ const toolCall = normalizeConnectionToolCall(record, message);
if (authorization !== undefined && headers !== undefined && typeof headers !== "function") {
const headerKeys = Object.keys(headers as Record<string, unknown>);
@@ -146,6 +205,9 @@ export function normalizeOpenApiConnectionDefinition(
if (headers !== undefined) {
result.headers = headers;
}
+ if (toolCall !== undefined) {
+ result.toolCall = toolCall;
+ }
if (operations !== undefined) {
result.operations = operations;
}
diff --git a/packages/eve/src/internal/authored-definition/openapi-connection.test.ts b/packages/eve/src/internal/authored-definition/openapi-connection.test.ts
index b5ab29b42..aa2885620 100644
--- a/packages/eve/src/internal/authored-definition/openapi-connection.test.ts
+++ b/packages/eve/src/internal/authored-definition/openapi-connection.test.ts
@@ -14,6 +14,16 @@ function validInput(overrides: Record<string, unknown> = {}) {
}
describe("normalizeOpenApiConnectionDefinition", () => {
+ it("preserves application-provided operation arguments", () => {
+ const tenantId = () => "tenant_1";
+ const result = normalizeOpenApiConnectionDefinition(
+ validInput({ toolCall: { providedArguments: { tenantId } } }),
+ MSG,
+ );
+
+ expect(result.toolCall?.providedArguments?.tenantId).toBe(tenantId);
+ });
+
describe("happy path", () => {
it("accepts a string spec URL and base URL", () => {
const result = normalizeOpenApiConnectionDefinition(validInput(), MSG);
diff --git a/packages/eve/src/public/connections/index.ts b/packages/eve/src/public/connections/index.ts
index 9d02db0e8..f5f7f51a7 100644
--- a/packages/eve/src/public/connections/index.ts
+++ b/packages/eve/src/public/connections/index.ts
@@ -21,6 +21,12 @@ export {
defineMcpClientConnection,
type McpClientConnectionDefinition,
} from "#public/definitions/connections/mcp.js";
+export type {
+ ConnectionToolCallDefinition,
+ ProvidedArgumentContext,
+ ProvidedArgumentsDefinition,
+ ProvidedArgumentValue,
+} from "#public/definitions/connections/tool-call.js";
export {
defineOpenAPIConnection,
type OpenAPIConnectionDefinition,
diff --git a/packages/eve/src/public/definitions/connections/mcp.test.ts b/packages/eve/src/public/definitions/connections/mcp.test.ts
index a2f0f7a46..a49901bb6 100644
--- a/packages/eve/src/public/definitions/connections/mcp.test.ts
+++ b/packages/eve/src/public/definitions/connections/mcp.test.ts
@@ -26,4 +26,18 @@ describe("defineMcpClientConnection", () => {
expect(typeof definition.auth).toBe("function");
});
+
+ it("accepts application-provided tool arguments", () => {
+ const definition = defineMcpClientConnection({
+ description: "Tenant-aware catalog",
+ toolCall: {
+ providedArguments: {
+ tenantId: ({ session }) => `tenant-for-${session.id}`,
+ },
+ },
+ url: "https://shop.example.com/mcp",
+ });
+
+ expect(typeof definition.toolCall?.providedArguments?.tenantId).toBe("function");
+ });
});
diff --git a/packages/eve/src/public/definitions/connections/mcp.ts b/packages/eve/src/public/definitions/connections/mcp.ts
index e4e586c8b..133ca45bd 100644
--- a/packages/eve/src/public/definitions/connections/mcp.ts
+++ b/packages/eve/src/public/definitions/connections/mcp.ts
@@ -3,6 +3,7 @@ import type {
HeadersDefinition,
ToolFilterDefinition,
} from "#runtime/connections/types.js";
+import type { ConnectionToolCallDefinition } from "#public/definitions/connections/tool-call.js";
import { normalizeAuthorizationSpec } from "#runtime/connections/validate-authorization.js";
import { stampConnectionProtocol } from "#public/definitions/connections/protocol.js";
import type { Approval } from "#public/definitions/approval.js";
@@ -72,6 +73,14 @@ export interface McpClientConnectionDefinition {
* session context.
*/
headers?: HeadersDefinition;
+ /**
+ * Per-call behavior for tools exposed by this MCP connection.
+ *
+ * Use `providedArguments` for application-owned values that should not be
+ * controlled by the model. eve removes configured keys from the model-facing
+ * input schema and adds their resolved values immediately before execution.
+ */
+ toolCall?: ConnectionToolCallDefinition;
/**
* Client-side tool filter. When set, the model sees only tools
* whose names pass the filter; `connection_search` drops all
diff --git a/packages/eve/src/public/definitions/connections/openapi.test.ts b/packages/eve/src/public/definitions/connections/openapi.test.ts
index a580ceadd..831408568 100644
--- a/packages/eve/src/public/definitions/connections/openapi.test.ts
+++ b/packages/eve/src/public/definitions/connections/openapi.test.ts
@@ -50,4 +50,19 @@ describe("defineOpenAPIConnection", () => {
expect(definition.spec).toBe(spec);
});
+
+ it("accepts application-provided operation arguments", () => {
+ const definition = defineOpenAPIConnection({
+ baseUrl: "https://api.example.com",
+ description: "test connection",
+ spec: "https://api.example.com/openapi.json",
+ toolCall: {
+ providedArguments: {
+ tenantId: ({ toolName }) => `${toolName}-tenant`,
+ },
+ },
+ });
+
+ expect(typeof definition.toolCall?.providedArguments?.tenantId).toBe("function");
+ });
});
diff --git a/packages/eve/src/public/definitions/connections/openapi.ts b/packages/eve/src/public/definitions/connections/openapi.ts
index a090ac695..0a97f70f8 100644
--- a/packages/eve/src/public/definitions/connections/openapi.ts
+++ b/packages/eve/src/public/definitions/connections/openapi.ts
@@ -7,6 +7,7 @@ import { normalizeAuthorizationSpec } from "#runtime/connections/validate-author
import { stampConnectionProtocol } from "#public/definitions/connections/protocol.js";
import type { Approval } from "#public/definitions/approval.js";
import { stampDefinitionKey } from "#public/tool-result-narrowing.js";
+import type { ConnectionToolCallDefinition } from "#public/definitions/connections/tool-call.js";
/**
* The OpenAPI document backing the connection: either an HTTPS URL the
@@ -91,6 +92,14 @@ export interface OpenAPIConnectionDefinition {
* values may be callbacks that receive the active session context.
*/
headers?: HeadersDefinition;
+ /**
+ * Per-call behavior for operations exposed by this OpenAPI connection.
+ *
+ * Use `providedArguments` for application-owned operation parameters. eve
+ * removes configured keys from the model-facing input schema and adds their
+ * resolved values immediately before building the HTTP request.
+ */
+ toolCall?: ConnectionToolCallDefinition;
/**
* Operation filter keyed on `operationId`. When set, the model sees
* only operations whose id passes the filter; `connection_search`
diff --git a/packages/eve/src/public/definitions/connections/tool-call.ts b/packages/eve/src/public/definitions/connections/tool-call.ts
new file mode 100644
index 000000000..67d384c21
--- /dev/null
+++ b/packages/eve/src/public/definitions/connections/tool-call.ts
@@ -0,0 +1,28 @@
+import type { SessionContext } from "#public/definitions/callback-context.js";
+import type { JsonValue } from "#public/types/json.js";
+
+/** Context available while resolving an application-provided connection tool argument. */
+export type ProvidedArgumentContext = SessionContext & {
+ /** Bare tool or operation name published by the remote connection. */
+ readonly toolName: string;
+};
+
+/** A static or per-call value for one application-provided connection tool argument. */
+export type ProvidedArgumentValue =
+ | JsonValue
+ | Promise<JsonValue>
+ | ((ctx: ProvidedArgumentContext) => JsonValue | Promise<JsonValue>);
+
+/**
+ * Connection tool argument values supplied by the application instead of the model.
+ *
+ * Configured keys are removed from remote input schemas before the schemas are
+ * exposed to the model, then resolved and added to every outgoing tool call.
+ */
+export type ProvidedArgumentsDefinition = Readonly<Record<string, ProvidedArgumentValue>>;
+
+/** Per-call behavior shared by tools exposed through a connection. */
+export interface ConnectionToolCallDefinition {
+ /** Application-owned arguments hidden from the model and added at execution time. */
+ readonly providedArguments?: ProvidedArgumentsDefinition;
+}
diff --git a/packages/eve/src/runtime/connections/mcp-client.test.ts b/packages/eve/src/runtime/connections/mcp-client.test.ts
index 0df8352f6..f9539367b 100644
--- a/packages/eve/src/runtime/connections/mcp-client.test.ts
+++ b/packages/eve/src/runtime/connections/mcp-client.test.ts
@@ -73,6 +73,81 @@ describe("McpConnectionClient", () => {
createMCPClient.mockReset();
});
+ it("hides provided arguments from schemas and adds resolved values at execution", async () => {
+ const execute = vi.fn().mockResolvedValue({ ok: true });
+ const toolsFromDefinitions = vi.fn().mockReturnValue({ lookup: { execute } });
+ const client = {
+ close: vi.fn(),
+ listTools: vi.fn().mockResolvedValue({
+ tools: [
+ {
+ description: "Look up a product",
+ inputSchema: {
+ additionalProperties: false,
+ properties: {
+ context: { type: "object" },
+ query: { type: "string" },
+ },
+ required: ["query", "context"],
+ type: "object",
+ },
+ name: "lookup",
+ },
+ ],
+ }),
+ toolsFromDefinitions,
+ };
+ createMCPClient.mockResolvedValue(client);
+
+ const resolver = vi.fn(({ session, toolName }) => ({
+ sessionId: session.id,
+ toolName,
+ }));
+ const mcpClient = new McpConnectionClient(
+ makeConnection({ toolCall: { providedArguments: { context: resolver } } }),
+ );
+ const ctx = ctxWithAuth(null);
+
+ await contextStorage.run(ctx, async () => {
+ await expect(mcpClient.getToolMetadata()).resolves.toEqual([
+ expect.objectContaining({
+ inputSchema: {
+ additionalProperties: false,
+ properties: { query: { type: "string" } },
+ required: ["query"],
+ type: "object",
+ },
+ name: "lookup",
+ }),
+ ]);
+ await expect(
+ mcpClient.executeTool("lookup", { context: { from: "model" }, query: "boots" }),
+ ).resolves.toEqual({ ok: true });
+ });
+
+ expect(toolsFromDefinitions).toHaveBeenCalledWith({
+ tools: [
+ expect.objectContaining({
+ inputSchema: expect.objectContaining({
+ properties: { query: { type: "string" } },
+ required: ["query"],
+ }),
+ }),
+ ],
+ });
+ expect(resolver).toHaveBeenCalledWith(expect.objectContaining({ toolName: "lookup" }));
+ expect(execute).toHaveBeenCalledWith(
+ {
+ context: {
+ sessionId: "session-1",
+ toolName: "lookup",
+ },
+ query: "boots",
+ },
+ expect.any(Object),
+ );
+ });
+
it("creates an HTTP MCP client with resolved connection headers", async () => {
const client = {
close: vi.fn(),
diff --git a/packages/eve/src/runtime/connections/mcp-client.ts b/packages/eve/src/runtime/connections/mcp-client.ts
index a947ea979..8bc006c0e 100644
--- a/packages/eve/src/runtime/connections/mcp-client.ts
+++ b/packages/eve/src/runtime/connections/mcp-client.ts
@@ -8,6 +8,10 @@ import type { ResolvedConnectionDefinition } from "#runtime/types.js";
import { evictScopedToken, resolveScopedToken } from "#runtime/connections/scoped-authorization.js";
import { resolveConnectionAuthorization } from "#runtime/connections/resolve-authorization.js";
import { isObject } from "#shared/guards.js";
+import {
+ omitProvidedArgumentsFromSchema,
+ resolveProvidedArguments,
+} from "#runtime/connections/provided-arguments.js";
import type {
AuthorizationDefinition,
ConnectionClient,
@@ -132,7 +136,13 @@ export class McpConnectionClient implements ConnectionClient {
);
}
- return await sdkTool.execute(args, { abortSignal: options?.abortSignal } as never);
+ const resolvedArgs = await resolveProvidedArguments({
+ args,
+ connection: this.#connection,
+ toolName,
+ });
+
+ return await sdkTool.execute(resolvedArgs, { abortSignal: options?.abortSignal } as never);
} catch (error) {
return await this.#rethrowClassified(error);
}
@@ -179,9 +189,15 @@ export class McpConnectionClient implements ConnectionClient {
// elements are `Tool<unknown, CallToolResult>`. The AI SDK's
// `ToolSet` constraint only admits `Tool<any | never, any | never>`,
// so a single-hop cast is required — the runtime shape is identical.
- const tools = client.toolsFromDefinitions({ tools: filteredTools }) as ToolSet;
+ const providedArgumentNames = Object.keys(this.#connection.toolCall?.providedArguments ?? {});
+ const projectedTools = filteredTools.map((tool) => ({
+ ...tool,
+ inputSchema: omitProvidedArgumentsFromSchema(tool.inputSchema, providedArgumentNames),
+ }));
+
+ const tools = client.toolsFromDefinitions({ tools: projectedTools }) as ToolSet;
- const metadata: ConnectionToolMetadata[] = filteredTools.map((t) => ({
+ const metadata: ConnectionToolMetadata[] = projectedTools.map((t) => ({
annotations: t.annotations as Record<string, unknown> | undefined,
description: t.description ?? "",
inputSchema: (t.inputSchema ?? {}) as Record<string, unknown>,
diff --git a/packages/eve/src/runtime/connections/openapi-client.test.ts b/packages/eve/src/runtime/connections/openapi-client.test.ts
index 42367ba16..9e9150a0a 100644
--- a/packages/eve/src/runtime/connections/openapi-client.test.ts
+++ b/packages/eve/src/runtime/connections/openapi-client.test.ts
@@ -142,6 +142,42 @@ describe("OpenApiConnectionClient", () => {
});
});
+ it("hides provided arguments from schemas and adds them to requests", async () => {
+ const fetchMock = vi.fn(
+ async (_url: URL, _init: RequestInit) =>
+ new Response(JSON.stringify({ id: "prj_1" }), {
+ status: 200,
+ headers: { "content-type": "application/json" },
+ }),
+ );
+ vi.stubGlobal("fetch", fetchMock);
+
+ const client = new OpenApiConnectionClient(
+ makeConnection({
+ toolCall: { providedArguments: { teamId: "team_from_app" } },
+ }),
+ );
+
+ const metadata = await client.getToolMetadata();
+ expect(metadata.find((item) => item.name === "getProject")?.inputSchema).toMatchObject({
+ properties: { id: { type: "string" } },
+ required: ["id"],
+ });
+ expect(
+ metadata.find((item) => item.name === "getProject")?.inputSchema.properties,
+ ).not.toHaveProperty("teamId");
+
+ await client.executeTool("getProject", {
+ id: "prj_1",
+ teamId: "team_from_model",
+ });
+
+ const [calledUrl] = fetchMock.mock.calls[0]!;
+ expect(String(calledUrl)).toBe(
+ "https://api.example.com/v1/projects/prj_1?teamId=team_from_app",
+ );
+ });
+
it("builds input schemas from Swagger 2.0 top-level parameters", async () => {
const client = new OpenApiConnectionClient(makeConnection({ spec: SWAGGER_SPEC, url: "" }));
const metadata = await client.getToolMetadata();
diff --git a/packages/eve/src/runtime/connections/openapi-client.ts b/packages/eve/src/runtime/connections/openapi-client.ts
index ef4d7706e..7748ae9df 100644
--- a/packages/eve/src/runtime/connections/openapi-client.ts
+++ b/packages/eve/src/runtime/connections/openapi-client.ts
@@ -3,6 +3,10 @@ import { tool, type ToolSet } from "ai";
import { createLogger } from "#internal/logging.js";
import type { ResolvedConnectionDefinition } from "#runtime/types.js";
import { passesToolFilter, resolveHeaders } from "#runtime/connections/mcp-client.js";
+import {
+ omitProvidedArgumentsFromSchema,
+ resolveProvidedArguments,
+} from "#runtime/connections/provided-arguments.js";
import {
HTTP_METHODS,
type OpenApiOperation,
@@ -157,11 +161,16 @@ export class OpenApiConnectionClient implements ConnectionClient {
const metadata: ConnectionToolMetadata[] = [];
const operationMap = new Map<string, OpenApiOperation>();
const tools: ToolSet = {};
+ const providedArgumentNames = Object.keys(this.#connection.toolCall?.providedArguments ?? {});
for (const operation of selected) {
+ const projectedInputSchema = omitProvidedArgumentsFromSchema(
+ operation.inputSchema,
+ providedArgumentNames,
+ );
let inputSchema: ToolSchema;
try {
- inputSchema = toInputSchema(operation.inputSchema);
+ inputSchema = toInputSchema(projectedInputSchema);
} catch (error) {
log.warn("omitting OpenAPI operation with an invalid input schema", {
connectionName: this.#connection.connectionName,
@@ -174,7 +183,7 @@ export class OpenApiConnectionClient implements ConnectionClient {
operationMap.set(operation.toolName, operation);
metadata.push({
description: operation.description,
- inputSchema: operation.inputSchema,
+ inputSchema: projectedInputSchema,
name: operation.toolName,
});
tools[operation.toolName] = tool({
@@ -418,6 +427,11 @@ export class OpenApiConnectionClient implements ConnectionClient {
args: Record<string, unknown>,
options?: ConnectionToolExecuteOptions,
): Promise<OpenApiToolResult> {
+ const resolvedArgs = await resolveProvidedArguments({
+ args,
+ connection: this.#connection,
+ toolName: operation.toolName,
+ });
const headers = await resolveHeaders(this.#connection);
let path = operation.pathTemplate;
@@ -425,7 +439,7 @@ export class OpenApiConnectionClient implements ConnectionClient {
const cookies: string[] = [];
for (const param of operation.parameters) {
- const value = args[param.name];
+ const value = resolvedArgs[param.name];
if (value === undefined || value === null) {
continue;
}
@@ -452,8 +466,8 @@ export class OpenApiConnectionClient implements ConnectionClient {
url.search = query.toString();
let body: string | undefined;
- if (operation.requestBody !== undefined && args.body !== undefined) {
- body = JSON.stringify(args.body);
+ if (operation.requestBody !== undefined && resolvedArgs.body !== undefined) {
+ body = JSON.stringify(resolvedArgs.body);
headers["content-type"] = operation.requestBody.contentType;
}
diff --git a/packages/eve/src/runtime/connections/provided-arguments.ts b/packages/eve/src/runtime/connections/provided-arguments.ts
new file mode 100644
index 000000000..0e9548aae
--- /dev/null
+++ b/packages/eve/src/runtime/connections/provided-arguments.ts
@@ -0,0 +1,74 @@
+import { buildCallbackContext } from "#context/build-callback-context.js";
+import type { ResolvedConnectionDefinition } from "#runtime/types.js";
+import { isObject } from "#shared/guards.js";
+import { parseJsonValue, type JsonValue } from "#shared/json.js";
+
+/** Resolves and merges application-provided arguments, with application values winning. */
+export async function resolveProvidedArguments(input: {
+ readonly args: unknown;
+ readonly connection: ResolvedConnectionDefinition;
+ readonly toolName: string;
+}): Promise<Record<string, unknown>> {
+ if (!isObject(input.args)) {
+ throw new Error(
+ `Tool "${input.toolName}" in connection "${input.connection.connectionName}" expected object arguments.`,
+ );
+ }
+
+ const definition = input.connection.toolCall?.providedArguments;
+ if (definition === undefined || Object.keys(definition).length === 0) {
+ return input.args;
+ }
+
+ let context:
+ | (ReturnType<typeof buildCallbackContext> & { readonly toolName: string })
+ | undefined;
+ const getContext = () =>
+ (context ??= {
+ ...buildCallbackContext(),
+ toolName: input.toolName,
+ });
+ const provided: Record<string, JsonValue> = {};
+
+ for (const [key, configuredValue] of Object.entries(definition)) {
+ const value =
+ typeof configuredValue === "function"
+ ? await configuredValue(getContext())
+ : await configuredValue;
+ try {
+ provided[key] = parseJsonValue(value);
+ } catch {
+ throw new Error(
+ `Connection "${input.connection.connectionName}" provided argument "${key}" must resolve to a JSON-serializable value.`,
+ );
+ }
+ }
+
+ return { ...input.args, ...provided };
+}
+
+/** Removes application-provided top-level properties from a remote tool schema. */
+export function omitProvidedArgumentsFromSchema<TSchema extends Record<string, unknown>>(
+ schema: TSchema,
+ names: readonly string[],
+): TSchema {
+ if (names.length === 0) {
+ return schema;
+ }
+
+ const omitted = new Set(names);
+ const projected: Record<string, unknown> = { ...schema };
+
+ if (isObject(schema.properties)) {
+ projected.properties = Object.fromEntries(
+ Object.entries(schema.properties).filter(([name]) => !omitted.has(name)),
+ );
+ }
+ if (Array.isArray(schema.required)) {
+ projected.required = schema.required.filter(
+ (name) => typeof name !== "string" || !omitted.has(name),
+ );
+ }
+
+ return projected as TSchema;
+}
diff --git a/packages/eve/src/runtime/resolve-connection.test.ts b/packages/eve/src/runtime/resolve-connection.test.ts
index d7cebe27f..c183b31df 100644
--- a/packages/eve/src/runtime/resolve-connection.test.ts
+++ b/packages/eve/src/runtime/resolve-connection.test.ts
@@ -5,15 +5,19 @@ import {
type CompiledConnectionDefinition,
} from "#compiler/manifest.js";
import type { CompiledModuleMap } from "#compiler/module-map.js";
+import type { ConnectionToolCallDefinition } from "#public/definitions/connections/tool-call.js";
import { resolveConnectionDefinition } from "#runtime/resolve-connection.js";
import type { ConnectionAuthResolver, HeadersDefinition } from "#runtime/connections/types.js";
describe("resolveConnectionDefinition", () => {
- it("preserves context-aware auth and header callbacks for request-time resolution", async () => {
+ it("preserves live MCP callbacks for request-time resolution", async () => {
const auth: ConnectionAuthResolver = (ctx) => ({
getToken: async () => ({ token: ctx.session.id }),
});
const headers: HeadersDefinition = (ctx) => ({ "X-Session": ctx.session.id });
+ const toolCall: ConnectionToolCallDefinition = {
+ providedArguments: { meta: ({ session }) => ({ sessionId: session.id }) },
+ };
const definition: CompiledConnectionDefinition = {
connectionName: "warehouse",
description: "Tenant warehouse",
@@ -32,6 +36,7 @@ describe("resolveConnectionDefinition", () => {
auth,
description: definition.description,
headers,
+ toolCall,
url: definition.url,
},
},
@@ -44,5 +49,6 @@ describe("resolveConnectionDefinition", () => {
expect(resolved.authorization).toBe(auth);
expect(resolved.headers).toBe(headers);
+ expect(resolved.toolCall).toBe(toolCall);
});
});
diff --git a/packages/eve/src/runtime/resolve-connection.ts b/packages/eve/src/runtime/resolve-connection.ts
index bb43b2631..beaa42d18 100644
--- a/packages/eve/src/runtime/resolve-connection.ts
+++ b/packages/eve/src/runtime/resolve-connection.ts
@@ -1,6 +1,7 @@
import type { CompiledConnectionDefinition } from "#compiler/manifest.js";
import type { CompiledModuleMap } from "#compiler/module-map.js";
import { expectObjectRecord } from "#internal/authored-module.js";
+import type { ConnectionToolCallDefinition } from "#public/definitions/connections/tool-call.js";
import { registerDefinitionSource, stampDefinitionKey } from "#public/tool-result-narrowing.js";
import { toErrorMessage } from "#shared/errors.js";
import type {
@@ -74,6 +75,7 @@ export async function resolveConnectionDefinition(
sourceId: string;
sourceKind: "module";
spec?: ResolvedConnectionDefinition["spec"];
+ toolCall?: Readonly<ConnectionToolCallDefinition>;
tools?: Readonly<ToolFilterDefinition>;
url: string;
} = {
@@ -109,6 +111,10 @@ export async function resolveConnectionDefinition(
result.headers = resolvedRecord.headers as Readonly<HeadersDefinition>;
}
+ if (resolvedRecord.toolCall !== undefined) {
+ result.toolCall = resolvedRecord.toolCall as Readonly<ConnectionToolCallDefinition>;
+ }
+
if (filter !== undefined) {
result.tools = filter as Readonly<ToolFilterDefinition>;
}
diff --git a/packages/eve/src/runtime/types.ts b/packages/eve/src/runtime/types.ts
index ef98aadd8..3e58d8394 100644
--- a/packages/eve/src/runtime/types.ts
+++ b/packages/eve/src/runtime/types.ts
@@ -10,6 +10,7 @@ import type { OutboundAuthFn } from "#public/agents/auth.js";
import type { StreamEventHook } from "#public/definitions/hook.js";
import type { Approval } from "#public/definitions/approval.js";
import type { ToolModelOutput } from "#public/definitions/tool.js";
+import type { ConnectionToolCallDefinition } from "#public/definitions/connections/tool-call.js";
import type {
AuthorizationDefinition,
ConnectionAuthResolver,
@@ -101,6 +102,7 @@ export interface ResolvedConnectionDefinition extends ResolvedModuleSourceRef {
readonly connectionName: string;
readonly description: string;
readonly headers?: Readonly<HeadersDefinition>;
+ readonly toolCall?: Readonly<ConnectionToolCallDefinition>;
/**
* Wire protocol. Selects the runtime client implementation. `tools`
* carries the connection's operation/tool filter regardless of