> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oneshotagent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Use OneShot tools directly in Claude Desktop, Cursor, Claude Code, and other MCP-compatible AI clients

## What is MCP?

The [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) is an open standard that allows AI applications to connect to external tools and data sources. OneShot provides an MCP server that exposes all our tools to any MCP-compatible client.

## Supported Clients

<CardGroup cols={2}>
  <Card title="Claude Desktop" icon="message">
    Anthropic's desktop application for Claude
  </Card>

  <Card title="Cursor" icon="code">
    AI-first code editor
  </Card>

  <Card title="Claude Code" icon="terminal">
    Anthropic's CLI for Claude
  </Card>

  <Card title="Any MCP Client" icon="plug">
    Works with any MCP-compatible application
  </Card>
</CardGroup>

## Installation

```bash theme={null}
npm install -g @oneshot-agent/mcp-server
```

Or use directly with npx (recommended for MCP configs):

```bash theme={null}
npx -y @oneshot-agent/mcp-server
```

## Configuration

The MCP server supports two authentication methods. **CDP Wallet is recommended** — no private keys in your config.

<Tabs>
  <Tab title="CDP Wallet (Recommended)">
    ### Claude Desktop

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

    ```json theme={null}
    {
      "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:

    ```json theme={null}
    {
      "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`:

    ```json theme={null}
    {
      "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](https://docs.cdp.coinbase.com/agentic-wallet/welcome).
  </Tab>

  <Tab title="Raw Private Key">
    ### Claude Desktop

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

    ### Cursor

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

    ### Claude Code

    ```json theme={null}
    {
      "mcpServers": {
        "oneshot": {
          "command": "npx",
          "args": ["-y", "@oneshot-agent/mcp-server"],
          "env": {
            "ONESHOT_WALLET_PRIVATE_KEY": "0xYourPrivateKey"
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

## 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 |

<Info>
  The server auto-detects which method to use. If `CDP_API_KEY_ID` is set, it uses CDP. Otherwise it falls back to `ONESHOT_WALLET_PRIVATE_KEY`.
</Info>

<Warning>
  Never commit secrets to version control. Use environment variables or a secrets manager.
</Warning>

## Available Tools

Once configured, your AI client will have access to all OneShot tools:

<Info>See [Pricing](/pricing) for current tool costs.</Info>

### Communication

| Tool            | Description                  |
| --------------- | ---------------------------- |
| `oneshot_email` | Send emails with attachments |
| `oneshot_voice` | Make phone calls             |
| `oneshot_sms`   | Send SMS messages            |

### Inbox

| Tool                     | Description                |
| ------------------------ | -------------------------- |
| `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 & Enrichment

| 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               |

### Person Intelligence

| Tool                           | Description                           |
| ------------------------------ | ------------------------------------- |
| `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     |

### 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                             |

### Web

| Tool                 | Description                           |
| -------------------- | ------------------------------------- |
| `oneshot_web_search` | Search the web, get results instantly |
| `oneshot_web_read`   | Read any URL as markdown + screenshot |

### Commerce

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

### Build

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

### Account

| Tool                             | Description               |
| -------------------------------- | ------------------------- |
| `oneshot_notifications`          | List agent notifications  |
| `oneshot_mark_notification_read` | Mark notification as read |
| `oneshot_get_balance`            | Get USDC wallet balance   |

## Usage Examples

Once configured, simply ask your AI client to perform actions:

<AccordionGroup>
  <Accordion title="Send an Email">
    > "Send an email to [john@example.com](mailto:john@example.com) with subject 'Meeting Tomorrow' and let him know we need to reschedule to 3pm"
  </Accordion>

  <Accordion title="Make a Phone Call">
    > "Call the restaurant at +14155551234 and make a reservation for 4 people at 7pm tonight"
  </Accordion>

  <Accordion title="Research a Topic">
    > "Research the latest developments in quantum computing and give me a summary with sources"
  </Accordion>

  <Accordion title="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"
  </Accordion>

  <Accordion title="Check Balance">
    > "What's my OneShot wallet balance?"
  </Accordion>
</AccordionGroup>

## Funding Your Agent

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

## Troubleshooting

<AccordionGroup>
  <Accordion title="Server not appearing in client">
    1. Verify the config file path is correct for your OS
    2. Restart your AI client after saving the config
    3. Check that `npx` is available in your PATH
  </Accordion>

  <Accordion title="'Private key required' or auth error">
    Ensure either 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.
  </Accordion>

  <Accordion title="Insufficient balance errors">
    1. Check your balance with `oneshot_get_balance`
    2. Send USDC to your agent's wallet address on Base Mainnet
  </Accordion>
</AccordionGroup>

## Links

<CardGroup cols={2}>
  <Card title="npm Package" icon="npm" href="https://www.npmjs.com/package/@oneshot-agent/mcp-server">
    View on npm registry
  </Card>

  <Card title="SDK Documentation" icon="book" href="/sdk/overview">
    Full SDK documentation
  </Card>

  <Card title="Pricing" icon="dollar-sign" href="/pricing">
    Detailed pricing information
  </Card>

  <Card title="MCP Protocol" icon="link" href="https://modelcontextprotocol.io/">
    Learn about MCP
  </Card>
</CardGroup>