> For the complete documentation index, see [llms.txt](https://docs.beamswap.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.beamswap.io/mcp-access.md). # Choose your connection Pick the connection first, then follow the guide for your AI. | Option | Good for | Advantages | Tradeoffs | | ------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- | | **Hosted MCP** | Most people using a remote MCP client | One server URL; no install or private-key setup; browser wallet approval | You open an approval page for requests that require consent; Beamswap hosts the service | | **Private vault link** | Letting your AI trade from an Agent Vault | One approval at setup; no browser approval per trade; the chain enforces your limits | Anyone with the link can trade inside your limits until you revoke it | | **Local MCP over stdio** | Desktop and CLI users | Runs on your computer; works with local clients; can automate paid API calls | Install/build once; keep the process available; configure a separate spending wallet | | **Private tunnel to local MCP** | ChatGPT users with tunnel access | Your MCP stays on your computer/private network | Advanced setup and account permissions; tunnel must keep running; local auto-payment rules still apply | | **Self-hosted remote MCP** | Teams operating their own infrastructure | You control hosting, domain and availability | Operate the backend, database and frontend approval flow; configure your own payment service and monitoring | ## Hosted Server URL: `https://api.beamswap.io/mcp`. Transport: **Streamable HTTP**. Connection authentication: **None**; paid actions are authorized separately with a wallet in the browser. After a tool prepares an approval request, open its Beamswap approval link, inspect the requested action and price, then approve or decline. Ask your AI to retrieve the result with the returned status capability. Keep these links and capabilities private: they identify your request and its result. ### Available tools | Tools | Hosted | Local | | --------------------------------------------------------------------------- | ------------------------------------------------------- | --------------------------------------------- | | `token_info`, `portfolio`, `swap_quote`, `swap_route`, `distribution_proof` | Browser approval and price/quota check | Automatic payment when a wallet is configured | | `watch_get`, `distribution_get`, `order_status`, `crosschain_status` | Free | Free | | `limit_order_prepare`, `automation_preview`, `crosschain_quote` | Free. Return a review link, never a transaction to sign | Free. Same | | `watch_delete` | Explicit browser approval, free | Free tool call | | `approval_status` | Retrieve an approved request's result | Not needed | | `session_create` | Wallet sign-in happens in the browser | Free wallet signature | | `spending_status`, `spending_pause` | Not available | Free. Read your caps and pause paid calls | | `watch_create`, `distribution_create` | Not available in this release | Available; paid | Hosted exposes fourteen tools; local exposes eighteen. Use the website or local/API setup to create distributions, and local/API setup to create watches. A prepared swap route does not execute a swap; a created distribution does not fund or open claims. The review-link tools open a prefilled form on beamswap.io where you sign in your own wallet. The public URL never trades from a vault. For that, use the private vault link below. ## Private vault link This is how your AI trades by itself from your [Agent Vault](https://docs.beamswap.io/agent-vaults). Link format: `https://api.beamswap.io/mcp/v/`. Transport: **Streamable HTTP**, same as the public URL. Connection authentication: none besides the private code in the link. The code is random, is stored by Beamswap only as a hash and is shown to you once, at the end of [setup](https://app.beamswap.io/agent/setup). Open your [agent dashboard](https://app.beamswap.io/agent) to see your links, revoke one or create another. A revoked link stops working at once. **Authorization header alternative.** A path with a secret in it can end up in server or proxy logs. If your client lets you set headers, send `POST https://api.beamswap.io/mcp/v` with `Authorization: Bearer ` and keep the code out of the URL. Beamswap also removes the code from any path it logs. Most consumer AI apps only take a URL, so the link form is the usual choice. ### Vault tools The private link exposes six tools. All of them act for that one vault only. | Tool | What it does | | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `vault_status` | Balances with USD values, your rules, today's spend and whether the vault is paused. Free. | | `vault_trade` | Sells one vault token for another at the current market price, with a maximum slippage (default 1%), a validity time and a short reason. | | `vault_limit_order` | Sells only at or above a price you name. It rests on CoW Protocol until the market reaches it or it expires. | | `vault_cancel` | Cancels one open order by its order ID. | | `vault_pause` | Pauses all trading in the vault at once. Only you can resume it, from your wallet. | | `vault_activity` | Recent orders with their status and the reason given for each. Free. | A trade that breaks a rule comes back as a plain error that names the rule, for example "This trade is 180 USD; your per-trade limit is 100 USD." No vault tool can withdraw, change your rules or resume trading. Those are owner-only on Base. A private link is rate limited. Treat it like a password: anyone who has it can trade inside your limits until you revoke it. Use the public URL, not the private one, for data and review-link tools. ## Local Use the [npm or source setup](https://github.com/BeamSwap/beamswap-mcp#run-the-local-server). Stdio means your AI client starts the program and exchanges messages with it locally. `https://api.beamswap.io` is the API the program calls, not a substitute for the remote MCP URL. Without a wallet key, connection and free tools still work. With a key, the server automatically pays within each tool's list-price ceiling, up to $50 for distribution creation. Only Base USDC payments to the configured treasury are allowed. This does not impose a session or daily budget. Limit the separate wallet's balance and configure the client's tool confirmations. [Uncertain payments block further payments](https://github.com/BeamSwap/beamswap-mcp/blob/main/docs/payment-recovery.md) until the owner checks the outcome. The local package can also trade for your vault. Set `BEAMSWAP_VAULT_URL` to your private vault link and it adds the six vault tools. They need no wallet key and no payment. They are included from version 0.2.0 (`npx -y @beamswapio/mcp@0.3.0`). If you choose "My own agent wallet" during setup, set `BEAMSWAP_VAULT_ADDRESS` to your vault instead (0.3.0 and later): your local agent signs its own trades with the wallet you registered, either `BEAMSWAP_WALLET_KEY` or a [MetaMask Agent Wallet](https://docs.beamswap.io/metamask-agent-wallet) with `BEAMSWAP_SIGNER=metamask`. ## Private tunnel OpenAI's [Secure MCP Tunnel](https://developers.openai.com/api/docs/guides/secure-mcp-tunnels) can connect ChatGPT to a local stdio program. Configure it to run `node /absolute/path/to/beamswap-mcp/dist/index.js`. You need the appropriate Platform organization and ChatGPT workspace permissions. This runs the local server's payment model. A tunnel does not add browser payment approval or a spending budget to the local package. ## Self-hosted The hosted implementation and approval frontend are in [beamswap-app-base](https://github.com/BeamSwap/beamswap-app-base). Deploy both with Postgres and your own HTTPS configuration using its hosted MCP runbook. This release pins hosted payments to Beamswap's Base USDC treasury; a different recipient requires a reviewed payment-policy change in both server and browser. Self-hosting the stdio package alone does not create an HTTP endpoint. Do not expose a shared, auto-paying private-key process as an unauthenticated public service. Use the hosted request-approval implementation or an authenticated private deployment. ## Direct API Developers can use [the REST API](https://app.beamswap.io/docs) with an x402 client instead. This is an alternative to MCP, not another MCP transport. Start with the [OpenAPI schema](https://api.beamswap.io/v1/openapi.json).