MCP Server

The OneShot MCP server puts every OneShot tool in Claude Desktop, Cursor, Claude Code, or any MCP client. It runs on your machine and signs payments with your wallet.

What is MCP?

The Model Context Protocol (MCP) is an open standard for connecting AI applications to external tools and data sources. OneShot’s MCP server exposes all OneShot tools to any MCP-compatible client.

Supported Clients

Claude Desktop

Anthropic’s desktop application for Claude

Cursor

AI-first code editor

Claude Code

Anthropic’s CLI for Claude

Any MCP Client

Any MCP-compatible application

Hosted endpoint (no local install)

Grok Bot, cloud runners, and any client that cannot spawn a local process: connect to https://win.oneshotagent.com/mcp with an access token

This page covers the local server (npx @oneshot-agent/mcp-server), which signs x402 payments with your wallet. Clients running in someone else’s cloud cannot hold a wallet key; they use the hosted endpoint, which bills your agent’s credit balance.

Installation

npm install -g @oneshot-agent/mcp-server

Or run it with npx (recommended for MCP configs):

npx -y @oneshot-agent/mcp-server

Configuration

The server supports two authentication methods. CDP Wallet is recommended because your config then holds no private keys.

CDP Wallet (Recommended)
Raw Private Key

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "oneshot": {
      "command": "npx",
      "args": ["-y", "@oneshot-agent/mcp-server"],
      "env": {
        "CDP_API_KEY_ID": "your-api-key-id",
        "CDP_API_KEY_SECRET": "your-api-key-secret",
        "CDP_WALLET_SECRET": "your-wallet-secret"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "oneshot": {
      "command": "npx",
      "args": ["-y", "@oneshot-agent/mcp-server"],
      "env": {
        "CDP_API_KEY_ID": "your-api-key-id",
        "CDP_API_KEY_SECRET": "your-api-key-secret",
        "CDP_WALLET_SECRET": "your-wallet-secret"
      }
    }
  }
}

Claude Code

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "oneshot": {
      "command": "npx",
      "args": ["-y", "@oneshot-agent/mcp-server"],
      "env": {
        "CDP_API_KEY_ID": "your-api-key-id",
        "CDP_API_KEY_SECRET": "your-api-key-secret",
        "CDP_WALLET_SECRET": "your-wallet-secret"
      }
    }
  }
}

Get credentials at Coinbase Agentic Wallet.

Claude Desktop

{
  "mcpServers": {
    "oneshot": {
      "command": "npx",
      "args": ["-y", "@oneshot-agent/mcp-server"],
      "env": {
        "ONESHOT_WALLET_PRIVATE_KEY": "0xYourPrivateKey"
      }
    }
  }
}

Cursor

{
  "mcpServers": {
    "oneshot": {
      "command": "npx",
      "args": ["-y", "@oneshot-agent/mcp-server"],
      "env": {
        "ONESHOT_WALLET_PRIVATE_KEY": "0xYourPrivateKey"
      }
    }
  }
}

Claude Code

{
  "mcpServers": {
    "oneshot": {
      "command": "npx",
      "args": ["-y", "@oneshot-agent/mcp-server"],
      "env": {
        "ONESHOT_WALLET_PRIVATE_KEY": "0xYourPrivateKey"
      }
    }
  }
}

Environment Variables

Variable	Required	Description
`CDP_API_KEY_ID`	Option A	Coinbase CDP API key ID
`CDP_API_KEY_SECRET`	Option A	Coinbase CDP API key secret
`CDP_WALLET_SECRET`	Option A	Coinbase CDP wallet secret
`ONESHOT_WALLET_PRIVATE_KEY`	Option B	Raw private key for signing payments
`ONESHOT_BUDGET_DAILY`	No	Max USDC the agent may spend per UTC day (see Spend Budgets)
`ONESHOT_BUDGET_PER_TRANSACTION`	No	Max USDC for any single call
`ONESHOT_BUDGET_ALERT_AT`	No	Fraction of the daily budget that triggers a warning (default `0.8`)
`ONESHOT_BUDGET_PAUSE_AT`	No	Fraction at which paid calls stop (default `1.0`)
`ONESHOT_BUDGET_ALERT_EMAIL`	No	Email for budget alerts

An invalid budget value (ONESHOT_BUDGET_DAILY=-1) fails startup with a message naming the variable. A blank value (ONESHOT_BUDGET_DAILY=) counts as unset and logs a warning on stderr, since ${VAR} templating produces a blank for an unset variable.

The server detects the method: CDP if CDP_API_KEY_ID is set, otherwise ONESHOT_WALLET_PRIVATE_KEY.

Never commit secrets to version control. Use environment variables or a secrets manager.

Available Tools

See Pricing for current tool costs.

Messaging

Tool	Description
`oneshot_email`	Send emails with attachments
`oneshot_voice`	Make phone calls
`oneshot_sms`	Send SMS messages
`oneshot_inbox_list`	List received emails
`oneshot_inbox_get`	Get a specific email
`oneshot_sms_inbox_list`	List received SMS messages
`oneshot_sms_inbox_get`	Get a specific SMS message

Research & Enrich

Tool	Description
`oneshot_research`	Deep web research with sources
`oneshot_people_search`	Search for people by title, company, etc.
`oneshot_enrich_profile`	Enrich person profile from LinkedIn/email
`oneshot_find_email`	Find someone’s email address
`oneshot_verify_email`	Verify email deliverability
`oneshot_deep_research_person`	Full dossier on a person (2-5 min)
`oneshot_social_profiles`	Find all social accounts for a person
`oneshot_article_search`	Find articles about a person
`oneshot_person_newsfeed`	Recent social posts with engagement
`oneshot_person_interests`	Analyze interests across categories
`oneshot_person_interactions`	Map followers, following, replies

Web & Browser

Tool	Description
`oneshot_browser`	Autonomous browser: navigate, click, extract
`oneshot_browser_create_profile`	Create persistent browser profile (cookies/sessions)
`oneshot_browser_list_profiles`	List all browser profiles
`oneshot_browser_delete_profile`	Delete a browser profile
`oneshot_web_search`	Search the web, get results instantly
`oneshot_web_read`	Read any URL as markdown + screenshot

Build

Tool	Description
`oneshot_build`	Build and deploy production websites
`oneshot_update_build`	Update an existing website

Commerce

Tool	Description
`oneshot_commerce_search`	Search for products
`oneshot_commerce_buy`	Purchase products

Account

Tool	Description
`oneshot_notifications`	List agent notifications
`oneshot_mark_notification_read`	Mark notification as read
`oneshot_get_balance`	Get USDC wallet balance
`oneshot_budget_status`	Today’s spend vs the configured budget (read-only; set the budget with `ONESHOT_BUDGET_*`)

Compute

Tool	Description
`oneshot_compute`	Create an autonomous goal (objective + budget); the orchestrator plans and executes
`oneshot_compute_status`	Get a compute goal’s status and budget
`oneshot_compute_tasks`	List tasks planned/executed under a goal
`oneshot_compute_cancel`	Cancel a goal and refund remaining budget
`oneshot_compute_respond`	Respond to a human-in-the-loop task
`oneshot_compute_pause`	Pause a recurring goal, keeping plan and progress
`oneshot_compute_resume`	Resume a paused recurring goal
`oneshot_compute_fund`	Top up a recurring goal’s USDC budget

Usage Examples

Ask your AI client in plain language. It picks the tool:

Send an Email

“Send an email to [email protected] with subject ‘Meeting Tomorrow’ and let him know we need to reschedule to 3pm”

Make a Phone Call

“Call the restaurant at +14155551234 and make a reservation for 4 people at 7pm tonight”

Research a Topic

“Research the latest developments in quantum computing and give me a summary with sources”

Build a Website

“Build a landing page for my new SaaS product called TaskFlow. It’s an AI-powered task management tool for remote teams”

Check Balance

“What’s my OneShot wallet balance?”

Funding Your Agent

The MCP server runs on Base Mainnet with real USDC. Send USDC to your agent’s wallet address on Base before making paid tool calls.

Troubleshooting

Server not appearing in client

Verify the config file path is correct for your OS
Restart your AI client after saving the config
Check that npx is available in your PATH

'Private key required' or auth error

Make sure either the CDP credentials (CDP_API_KEY_ID, CDP_API_KEY_SECRET, CDP_WALLET_SECRET) or ONESHOT_WALLET_PRIVATE_KEY is set in the env section of your config.

Insufficient balance errors

Check your balance with oneshot_get_balance
Send USDC to your agent’s wallet address on Base Mainnet

npm Package

npm registry listing

SDK Documentation

Full SDK documentation

Pricing

Detailed pricing

MCP Protocol

Learn about MCP

Get Started

SDK

What is MCP?

Supported Clients

Claude Desktop

Cursor

Claude Code

Any MCP Client

Hosted endpoint (no local install)

Installation

Configuration

Claude Desktop

Cursor

Claude Code

Claude Desktop

Cursor

Claude Code

Environment Variables

Available Tools

Messaging

Research & Enrich

Web & Browser

Build

Commerce

Account

Compute

Usage Examples

Funding Your Agent

Troubleshooting

Links

npm Package

SDK Documentation

Pricing

MCP Protocol

​What is MCP?

​Supported Clients

Claude Desktop

Cursor

Claude Code

Any MCP Client

Hosted endpoint (no local install)

​Installation

​Configuration

​Claude Desktop

​Cursor

​Claude Code

​Claude Desktop

​Cursor

​Claude Code

​Environment Variables

​Available Tools

​Messaging

​Research & Enrich

​Web & Browser

​Build

​Commerce

​Account

​Compute

​Usage Examples

​Funding Your Agent

​Troubleshooting

​Links

npm Package

SDK Documentation

Pricing

MCP Protocol

What is MCP?

Supported Clients

Installation

Configuration

Claude Desktop

Cursor

Claude Code

Claude Desktop

Cursor

Claude Code

Environment Variables

Available Tools

Messaging

Research & Enrich

Web & Browser

Build

Commerce

Account

Compute

Usage Examples

Funding Your Agent

Troubleshooting

Links