Choose your connection
Pick the connection first, then follow the guide for your AI.
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
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.
Link format: https://api.beamswap.io/mcp/v/<capability>. 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. Open your agent dashboard 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 <capability> 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.
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. 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 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 with BEAMSWAP_SIGNER=metamask.
Private tunnel
OpenAI's Secure MCP Tunnel 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. 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 with an x402 client instead. This is an alternative to MCP, not another MCP transport. Start with the OpenAPI schema.