> For the complete documentation index, see [llms.txt](https://docs.vapinetwork.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.vapinetwork.ai/agents/in-your-ai-app/use-vapi-in-claude-cursor-and-codex.md). # MCP server for Claude, Cursor and Codex The local vAPI Network MCP server connects Claude, Cursor, and Codex to buyer-controlled wallets and x402 API tools. {% hint style="info" %} Agents is coming soon. This page describes how it works at launch. {% endhint %} The vAPI Network MCP server connects Claude, Cursor, and Codex to the local vapi-network client over stdio. `vapi mcp` runs a local MCP server over stdio. New users can start with the [Overview Quickstart](https://docs.vapinetwork.ai/quickstart). ## Start the server Run the server through the published package: ```bash npx -y vapi-network mcp ``` Add the same command and arguments to an MCP client. The public client README shows this generic stdio shape for Claude Code, Claude Desktop, and Cursor: ```json { "mcpServers": { "vapi": { "command": "npx", "args": ["-y", "vapi-network", "mcp"] } } } ``` If the vault is password-protected, open its session in your own terminal: ```bash vapi vault unlock ``` The vault password does not go into the MCP configuration file or to the agent. For a non-terminal process, set `VAPI_VAULT_PASSWORD` in the client environment. ## Use a named account Create a separate account for an agent and set its caps before you connect the agent: ```bash vapi accounts add agent-claude --label "claude code" vapi accounts caps agent-claude --per-day 5 ``` Pin the MCP process to that account: ```json { "mcpServers": { "vapi": { "command": "npx", "args": ["-y", "vapi-network", "mcp", "--account", "agent-claude"], "env": { "VAPI_WALLET": "agent-claude", "VAPI_NO_SECRETS": "1" } } } } ``` {% hint style="info" %} `call.read` and all `swarm.*` tools require the 0.8.0 preview: ```bash npx -y vapi-network@next mcp ``` For both configuration examples, replace the package argument with `vapi-network@next`. {% endhint %} Spend caps belong to the account. The defaults are `$0.10` per call and `$1.00` per UTC day. `call.pay` applies the selected account's own caps before it signs. You can also pass `wallet` to a tool that accepts it. Without that input, the server uses the session account, then `VAPI_WALLET`, then the machine default. `wallet.use` changes the account for this MCP process only. It does not change the default used by your terminal. Reads do not need a vault password. A payment opens the selected account for that payment. ## Tools | Tool | Input | Result | | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `vapi.status` | None | Status report with owner, vault, accounts, unfinished movements, and next commands | | `vapi.accounts` | None | Local accounts with addresses, balances, Router usage, caps, ceilings, and link status | | `vapi.siblings` | `account` | The owner's linked accounts across devices, without keys, phrases, or tokens | | `accounts.add` | `name`, `caps`, `routerAllowanceUsd`, `link` | Creates a derived account and returns trusted-device or owner-approval link status | | `accounts.caps` | `name`, `perCallUsd`, `perDayUsd`, `ceilingUsd` | Lowers local spend caps or the ceiling; raising or disabling the ceiling stays in the terminal | | `accounts.send` | `from`, `to`, `amountUsd`, `network` | Relayed transfer status; an unknown result names the terminal resume command | | `auth.link` | optional `label`, optional `account` | Starts linking this wallet to a person's vAPI account for browser approval with default permissions only; returns the code and URL | | `auth.status` | `wallet` | Link status, owner, label, permissions, Router-key presence, and any pending browser approval | | `router.models` | None | Model ids available from vAPI Router | | `router.usage` | `wallet` | Router usage plus the linked owner's stake and stake-funded Compute | | `router.chat` | `model`, `messages[]`, `max_tokens`, `wallet` | Completion `content`, resolved `model`, and token `usage`; the Router key stays in the OS secret store and is never returned | | `router.buy` | `usd` (`1`, `5`, `20`, or `50`), `wallet` | Receipt summary and the new vAPI Router balance; the Router key stays in the OS secret store and is never returned | | `call.search` | `query`, `kinds[]`, `network`, `limit`, `cursor`, `includeUnverified` | One discovery page: `items` with `group`, `fee` and `verification`, plus `nextCursor`, `unavailableKinds`, `rankingVersion` | | `call.inspect` | `id`, `endpoint` | A listing's `verification`, `fee`, `liveness`, `conformance`, identity, request contract and live quote | | `call.pay` | `wallet`, `id` or `url`, `method`, `endpoint`, `body`, `contentType`, `network`, `expectedPayTo`, `maxPriceUsd` | `wallet`, `status`, `body`, `payment`, `verification` for a registry listing, and `expectedRequest` when a 402 named one | | `call.read` (0.8.0 preview) | `url` | Agent-run-only GET result from an origin paid during the run; never pays and redacts its SIWX proof | | `wallet.address` | `wallet` | `wallet`, `address` | | `wallet.balance` | `wallet` | `wallet`, `address`, `balances[]` per configured network | | `wallet.accounts` | `wallet` | `wallet`, `accounts[]` with USDC, gas balance and deposit guidance | | `wallet.list` | None | `wallet`, `default`, and every wallet with caps in atomic USDC and dollars, balances, and `balanceError` when an RPC is unreachable | | `wallet.use` | `name` | `wallet`, `active`, `previous`, `scope: "session"` | | `wallet.fund` | `wallet`, `amountUsd` | `wallet`, `address`, `network`, `url`, `instructions` | | `receipts.list` | `wallet`, `allWallets`, `limit` | `wallet`, `receipts[]` | | `receipts.stats` | `wallet`, `allWallets`, `range` | `wallet`, `range`, `generatedAt`, `totals`, `outcomes`, `latency`, `topServices`, `search` | | `support.report` | `message`, `includeAddresses`, `send` | `path`, `issueUrl`, the report itself, and `responseCode` when sent | | `swarm.setup` (0.8.0 preview) | `name`, `agents` or `roles[]`, `strategy`, `targetsUsd`, `caps`, `treasuryCaps`, `network`, `model`, `fundUsd`, `from` | Swarm state, member setup status, link or caps next steps, and optional funding result | | `swarm.add` (0.8.0 preview) | `name`, `role`, `targetUsd`, `weight` | Updated swarm and member setup status | | `swarm.leave` (0.8.0 preview) | `name`, `member` | Member sweep and removal status | | `swarm.fund` (0.8.0 preview) | `name`, `amountUsd`, `from` | Treasury funding result or owner funding instructions | | `swarm.rebalance` (0.8.0 preview) | `name`, `targetsUsd` | Movement, blocked legs, skipped members, and balance status | | `swarm.status` (0.8.0 preview) | `name` | Treasury, members, balances, links, allocation totals (allocated, swept out, and net per member), and open movements | | `swarm.dissolve` (0.8.0 preview) | `name` | Member and treasury sweep results, then swarm removal status | | `swarm.run` (0.8.0 preview) | `name`, `task`, `mode`, `lead`, `budgetUsd`, `drawUsd`, `detach` | Attached member results, or detached run ids and skipped members | | `swarm.allocate` (0.8.0 preview) | `amountUsd`, `reason`, `requestId` | Agent-only treasury allocation inside a swarm run; direct MCP calls are refused | | `swarm.delegate` (0.8.0 preview) | `member`, `task`, `budgetUsd`, `requestId` | Agent-only one-level delegation inside a swarm run; direct MCP calls are refused | | `swarm.runs` (0.8.0 preview) | `name` | Stored background runs with their latest runtime status | `call.search` returns vAPI-verified listings and mirrored external catalogues by default. Set `includeUnverified` to `true` to add self-listed APIs that passed the automated x402 probe but were not reviewed. Inspect the request contract and quote before paying an unverified listing. When a paid call has an uncertain outcome, `call.pay` returns `settlement_unknown` and tells you not to retry automatically. It names the receipt for `vapi pay --resume `. `call.read` works only inside an agent run. It sends a GET request to an HTTPS origin paid during that run, can use SIWX sign-in, and never pays. A direct MCP call is refused. Reflected SIWX headers and signatures are redacted from its result. `swarm.allocate` and `swarm.delegate` are agent-only tools inside a swarm run. The first draws treasury capital for the current member. The second delegates one level of work with a hard budget. Direct MCP calls to either tool are refused. `swarm.run` defaults to lead mode. Set `detach` to start local background work. MCP cannot export a member key. ## Link from Claude or Cursor Claude, Cursor, or Codex can call `auth.link` with a `label`. The tool returns a code and URL. Open the console link at `https://api.vapinetwork.ai/link?code=...` in your browser, approve it with your wallet, and set the agent's daily vAPI Router allowance in USD. The code lasts 20 minutes. `auth.status` reports the link, owner, label, permissions, Router-key presence, and any pending browser approval. `auth.link` grants the default permissions `mcp:call` and `router.use` only. To grant `call.publish`, run this command in your terminal: ```bash vapi login --account agent-claude --publish ``` The Router key stays in the OS secret store, and no tool returns it. After the link is approved, `router.chat` and `router.buy` work from the linked wallet. See [Agents](/agents/readme.md) for the setup flow and [Owner and agents](/agents/control/owner-and-agents.md) for the permissions model. ## Deprecated aliases These pre-namespace names still work and behave like their replacements. Each result carries a one-line `DEPRECATED:` notice. They are scheduled for removal in a later release. | Alias | Use instead | | --------- | ---------------- | | `search` | `call.search` | | `inspect` | `call.inspect` | | `call` | `call.pay` | | `wallet` | `wallet.balance` | ## What the MCP server cannot do The MCP server cannot rename, remove, restore, back up, or import an account, and it cannot export a key. It cannot cancel a movement or set `--replace-expired-restored`, `--bind-legacy-addresses`, or `--confirm-worker-stopped`. No tool returns a key, recovery phrase, passphrase, or token. Recovery and secret-export actions stay in the CLI, in front of a person. The agent cannot reach secrets through MCP. The MCP package does not import the separate secrets entry point, and no MCP tool returns recovery data or key material. ## Next * [Run your first agent](/agents/quickstart.md) * [Hosted MCP](/agents/in-your-ai-app/hosted-mcp.md) * [SDK](https://docs.vapinetwork.ai/reference/sdk/sdk) Checked on 2026-10-02. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.vapinetwork.ai/agents/in-your-ai-app/use-vapi-in-claude-cursor-and-codex.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.