Connect any agent

Connect any agent

The gateway does not care which coding tool calls it. Any agent that can either send an HTTP request before it runs a tool, or speak MCP, can be governed. Claude Code and Cursor have ready-made wiring in the quickstart; this page covers everything else.

Two ways in

• A pre-tool hook: If your agent can run a script before each tool call, use the hook contract below. This is the same path Claude Code and Cursor use.
• The MCP proxy: If your agent speaks MCP (JSON-RPC tools/call), point it at the gateway and you are done. No script needed.

The pre-tool hook contract

Before your agent runs a tool, send the call to the gateway and act on the answer. The contract has three parts.

1. POST the tool call to /v1/mcp/hook with your agent key. Send tool_name, arguments, session_id and tool_use_id.
2. Read the decision in the response: allow, deny, approval_required or rate_limited.
3. Run the tool only on allow. On deny block it. On approval_required poll until you get a final answer. On rate_limited back off.

decision=$(curl -s -X POST "$VW_GATEWAY_URL/v1/mcp/hook" \
  -H "Authorization: Bearer $VW_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tool_name":"Bash","arguments":{"command":"ls"},"session_id":"run-123","tool_use_id":"call-1"}' \
  | jq -r .decision)

[ "$decision" = "allow" ] && run_the_tool || echo "blocked: $decision"

The bundled script scripts/vw-tool-hook.sh already implements this, including approval polling and fail-modes. If your agent passes the tool call to a script on stdin, you can reuse it directly. See the API reference for every field.

The MCP proxy

If your agent already talks to tools over MCP, route those calls through the gateway instead of straight to the tool server. The gateway checks each call and forwards the allowed ones.

• Send your JSON-RPC tools/call requests to POST /v1/mcp.
• Authenticate with your agent key as a bearer token.
• When a tool needs approval, the gateway replies with a JSON-RPC error (code -32001) that tells you where to poll.

No adapter script is needed for this path. Any MCP client works.

Agents without a hook

Some terminal agents (for example Codex CLI, Aider and Gemini CLI) do not yet have a built-in way to run a script before each tool call. You have two choices.

• Use the MCP proxy: If the agent can reach tools over MCP, the proxy path above governs it with no hook.
• Wrap the tool step: If you control how the agent runs tools, add the hook contract call at that point: POST to /v1/mcp/hook and only run the tool on allow.