Connect your AI
Choose hosted or local mode first. Hosted mode uses https://api.beamswap.io/mcp and asks for wallet approval in the browser. Local mode uses the npm package or source build. Wherever this guide shows node /absolute/path/to/beamswap-mcp/dist/index.js, you can use npx -y @beamswapio/mcp@0.3.0 for the packaged server instead.
Two kinds of connection
Public hosted URL (
https://api.beamswap.io/mcp): data, quotes and review links. Requests that cost money or need consent open a Beamswap approval page.Private vault link (
https://api.beamswap.io/mcp/v/<your-private-code>): lets your AI trade from your Agent Vault without a browser approval for each trade. You get it once, at the end of setup. You can create or revoke links on your agent dashboard.
To add the private link, follow the steps for your client below and paste the private link where the guide shows the hosted URL. A client that lets you set request headers can send the private code as Authorization: Bearer <private code> to https://api.beamswap.io/mcp/v instead. Details in MCP access.
Anyone with the private link can trade inside your limits, so keep it private. Never paste it into a public chat, a shared file or source control. Add both URLs if you want data tools and trading in the same AI.
Provider menus and plan access can change. These instructions were checked against official documentation on 16 September 2026. Protocol tests do not mean every provider account or plan has been tested.
Claude
Hosted: use Claude's custom remote connector setup and enter https://api.beamswap.io/mcp. No Beamswap API key is required. Enable the connector in the conversation and ask it to list its tools.
Claude Desktop, local: open Settings > Developer > Edit Config. Add the mcpServers.beamswap entry from the README, keeping other entries. Restart Claude Desktop and check that Beamswap is connected.
Claude Code, local:
claude mcp add --transport stdio --scope user beamswap -- node "/absolute/path/to/beamswap-mcp/dist/index.js"Sources: remote connectors, Desktop setup, Claude Code.
ChatGPT
For accounts with developer mode, open Settings > Security and login and enable Developer mode. Open Plugins, select the plus button, and create an MCP connection with URL https://api.beamswap.io/mcp. Select no authentication if requested. Add the connection to a conversation and inspect its tools. Workspace policy can restrict this feature.
Advanced users can select Tunnel instead and connect the local stdio server through Secure MCP Tunnel. Keep the tunnel client running. Most users should choose hosted mode.
Sources: ChatGPT connection guide, private tunnels.
Gemini
Use Gemini CLI for MCP. The ordinary Gemini chat interface is a separate product and is not covered by these commands.
Run /mcp inside Gemini CLI to inspect the connection. Review the available tools before granting tool access.
Source: Gemini CLI MCP setup.
Perplexity
If your account offers a Remote custom connector, enter the hosted MCP URL in Connectors and enable it for the conversation. Availability varies by app, plan and workspace.
For the Mac app's local mode, open Settings > Connectors, install the PerplexityXPC helper if prompted, then add a connector with command node /absolute/path/to/beamswap-mcp/dist/index.js. Save, wait for Running, and enable it under Sources. Configure the local process environment separately before using paid tools.
Sources: local setup, custom connector availability.
Grok and Grok Bot
Grok web: open Connectors, choose New Connector > Custom, and enter the hosted MCP URL. Enable it in a conversation. Team administrators may need to allow custom connectors.
Grok Build, local:
Grok Bot: where its connector settings expose the custom connector, use hosted mode. Otherwise ask it to prepare a recipient CSV or review your plan, then finish through the Beamswap website. Do not put a wallet private key into a Bot's shared files or chat. We have not verified a separate native Grok Bot MCP installation flow.
Sources: Grok connectors, Grok Build MCP, Grok Bot.
Codex
Inspect the server with /mcp. If it has not appeared, reconnect or restart the client. Use the client environment configuration to forward BEAMSWAP_WALLET_KEY only for local paid mode.
Source: Codex MCP.
Cursor
Open Cursor's MCP settings or edit ~/.cursor/mcp.json. Merge this entry with your existing servers:
For local mode, replace url with the command and arguments from the README. Enable the server and inspect its available tools before granting access.
Source: Cursor MCP.
Any other MCP client
If the client supports Streamable HTTP, use the hosted URL. If it supports stdio, use command node and the absolute path to the built file. A client that supports only legacy SSE is not covered by the hosted endpoint. Follow the client's documentation rather than changing the URL to an invented /sse path.
MetaMask Agent Wallet
To keep a raw private key out of your local config, sign with a MetaMask Agent Wallet (needs @beamswapio/mcp@0.3.0).
First request
“List the Beamswap tools without spending anything. Then explain how to check the Base balances of [my public wallet address]. Ask before making a paid request.”
With a vault link, a good first message is: "Show my vault status and today's spend. Do not trade." The AI reads your vault and your limits and places nothing.
Listing tools is free. A prompt asking for confirmation is guidance to the model, not an enforced local spending limit. Hosted browser approval and local automatic payments are different modes.