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

# Installation

> Connect the SolvaPay MCP Server to your AI assistant.

export const McpConnectActions = () => {
  const [isOpen, setIsOpen] = React.useState(false);
  const [copiedLabel, setCopiedLabel] = React.useState('');
  const endpoint = 'https://mcp.solvapay.com/mcp';
  const serverName = 'solvapay';
  const createCursorDeepLink = apiKey => {
    const config = {
      url: endpoint,
      headers: {
        'X-API-Key': apiKey || 'YOUR_API_KEY_HERE'
      }
    };
    const encodedConfig = btoa(JSON.stringify(config));
    return `cursor://anysphere.cursor-deeplink/mcp/install?name=${encodeURIComponent(serverName)}&config=${encodeURIComponent(encodedConfig)}`;
  };
  const copyText = async (text, label) => {
    try {
      await navigator.clipboard.writeText(text);
      setCopiedLabel(`${label} copied`);
      setTimeout(() => {
        setCopiedLabel('');
      }, 1800);
    } catch {
      setCopiedLabel(`Could not copy ${label}`);
      setTimeout(() => {
        setCopiedLabel('');
      }, 2200);
    }
  };
  const openCursorInstall = () => {
    const enteredKey = window.prompt('Enter your SolvaPay API key (from Settings > API Keys). Leave empty to add the placeholder and update it later.');
    const deeplink = createCursorDeepLink(enteredKey?.trim());
    window.location.href = deeplink;
  };
  const vscodeConfig = JSON.stringify({
    servers: {
      solvapay: {
        type: 'http',
        url: endpoint,
        headers: {
          'X-API-Key': 'YOUR_API_KEY_HERE'
        }
      }
    }
  }, null, 2);
  const claudeDesktopConfig = JSON.stringify({
    mcpServers: {
      solvapay: {
        url: endpoint,
        headers: {
          'X-API-Key': 'YOUR_API_KEY_HERE'
        }
      }
    }
  }, null, 2);
  const addMcpCommand = `npx add-mcp ${endpoint} --header "X-API-Key: YOUR_API_KEY_HERE"`;
  return <div className="not-prose">
      <button type="button" onClick={() => setIsOpen(!isOpen)} className="inline-flex items-center gap-2 rounded-full border border-zinc-300 bg-white px-4 py-2 text-sm font-semibold text-zinc-900 transition hover:bg-zinc-50 dark:border-white/20 dark:bg-white/[0.03] dark:text-zinc-100 dark:hover:bg-white/[0.06]">
        Connect SolvaPay MCP
        <span aria-hidden>{isOpen ? '▴' : '▾'}</span>
      </button>

      {isOpen && <div className="mt-3 max-w-[560px] rounded-2xl border border-zinc-200 bg-white p-3 shadow-sm dark:border-white/15 dark:bg-white/[0.03]">
          <button type="button" className="w-full rounded-xl border border-zinc-200 bg-zinc-50 p-3 text-left text-zinc-900 transition-colors hover:bg-zinc-100 dark:border-white/15 dark:bg-white/[0.04] dark:text-zinc-100 dark:hover:bg-white/[0.08]" onClick={openCursorInstall}>
            <span className="block text-sm font-semibold leading-tight">Install in Cursor</span>
            <span className="mt-1.5 block text-xs leading-snug text-zinc-600 dark:text-zinc-400">
              One-click deeplink install with SolvaPay endpoint
            </span>
          </button>

          <button type="button" className="mt-2 w-full rounded-xl border border-zinc-200 bg-zinc-50 p-3 text-left text-zinc-900 transition-colors hover:bg-zinc-100 dark:border-white/15 dark:bg-white/[0.04] dark:text-zinc-100 dark:hover:bg-white/[0.08]" onClick={() => copyText(endpoint, 'Claude.ai connector URL')}>
            <span className="block text-sm font-semibold leading-tight">Copy Claude.ai connector URL</span>
            <span className="mt-1.5 block text-xs leading-snug text-zinc-600 dark:text-zinc-400">
              Paste into Claude.ai Settings &gt; Connectors — sign in with your SolvaPay account
            </span>
          </button>

          <div className="my-2 h-px bg-zinc-200 dark:bg-white/10" />

          <button type="button" className="w-full rounded-xl border border-zinc-200 bg-zinc-50 p-3 text-left text-zinc-900 transition-colors hover:bg-zinc-100 dark:border-white/15 dark:bg-white/[0.04] dark:text-zinc-100 dark:hover:bg-white/[0.08]" onClick={() => copyText(vscodeConfig, 'VS Code config')}>
            <span className="block text-sm font-semibold leading-tight">Copy VS Code config</span>
            <span className="mt-1.5 block text-xs leading-snug text-zinc-600 dark:text-zinc-400">
              Paste into `.vscode/mcp.json` or user `mcp.json`
            </span>
          </button>

          <button type="button" className="mt-2 w-full rounded-xl border border-zinc-200 bg-zinc-50 p-3 text-left text-zinc-900 transition-colors hover:bg-zinc-100 dark:border-white/15 dark:bg-white/[0.04] dark:text-zinc-100 dark:hover:bg-white/[0.08]" onClick={() => copyText(claudeDesktopConfig, 'Claude Desktop config')}>
            <span className="block text-sm font-semibold leading-tight">
              Copy Claude Desktop config
            </span>
            <span className="mt-1.5 block text-xs leading-snug text-zinc-600 dark:text-zinc-400">
              Paste into `claude_desktop_config.json`
            </span>
          </button>

          <button type="button" className="mt-2 w-full rounded-xl border border-zinc-200 bg-zinc-50 p-3 text-left text-zinc-900 transition-colors hover:bg-zinc-100 dark:border-white/15 dark:bg-white/[0.04] dark:text-zinc-100 dark:hover:bg-white/[0.08]" onClick={() => copyText(endpoint, 'MCP endpoint')}>
            <span className="block text-sm font-semibold leading-tight">Copy MCP endpoint</span>
            <span className="mt-1.5 block text-xs leading-snug text-zinc-600 dark:text-zinc-400">
              Use this URL in any Streamable HTTP MCP client
            </span>
          </button>

          <button type="button" className="mt-2 w-full rounded-xl border border-zinc-200 bg-zinc-50 p-3 text-left text-zinc-900 transition-colors hover:bg-zinc-100 dark:border-white/15 dark:bg-white/[0.04] dark:text-zinc-100 dark:hover:bg-white/[0.08]" onClick={() => copyText(addMcpCommand, 'add-mcp command')}>
            <span className="block text-sm font-semibold leading-tight">Copy add-mcp command</span>
            <span className="mt-1.5 block text-xs leading-snug text-zinc-600 dark:text-zinc-400">
              CLI shortcut for custom setup flows
            </span>
          </button>

          <div className="mt-2 min-h-5 text-xs font-medium text-zinc-600 dark:text-zinc-400">
            {copiedLabel}
          </div>
        </div>}
    </div>;
};

## Connect from this page

Use the action button below to connect SolvaPay MCP with the correct endpoint.

<McpConnectActions />

OAuth-capable clients (Claude.ai, Claude Desktop) handle authentication automatically — just log in with your SolvaPay account. Config-based clients (Cursor, VS Code) require an API key from **SolvaPay Console > Settings > API Keys**.

## Cursor IDE

1. Open **Connect SolvaPay MCP** and select **Install in Cursor**.
2. Enter your API key when prompted, or continue with `YOUR_API_KEY_HERE`.
3. Confirm the install prompt in Cursor.
4. If you installed with the placeholder key, update `X-API-Key` in Cursor MCP settings.
5. Reload or toggle the SolvaPay MCP server in Cursor settings.

After setup, you should see SolvaPay tools available in Cursor chat.

## VS Code

1. Open **Connect SolvaPay MCP** and select **Copy VS Code config**.
2. Paste into `.vscode/mcp.json` (workspace) or your user `mcp.json`.
3. Replace `YOUR_API_KEY_HERE` with your SolvaPay API key.
4. Run **MCP: List Servers** and start the `solvapay` server if needed.
5. Reload VS Code if tools do not appear immediately.

After setup, SolvaPay tools are available in Copilot Chat.

## Claude.ai (Web & Mobile)

SolvaPay can be added as a connector directly inside Claude.ai — no local configuration or API keys needed.

1. Go to **Settings > Connectors** in Claude.ai.
2. Click **Add** and enter the MCP server URL:
   ```
   https://mcp.solvapay.com/mcp
   ```
3. Click **Add custom connector**. Claude will redirect you to the SolvaPay login page.
4. Sign in with your SolvaPay provider account (email code, Google, or GitHub).
5. Review the permissions and click **Authorize**.
6. The connector is now active. Enable it in any conversation via the **+** button > **Connectors**.

OAuth is handled automatically — Claude securely stores the access token so you don't need to re-authorize each session. Only existing SolvaPay providers can connect; no new account is created during this flow.

## Claude Desktop

Use **Connect SolvaPay MCP** and select **Copy Claude Desktop config**.

Paste it into:

* **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
* **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

Then replace `YOUR_API_KEY_HERE` with your SolvaPay API key.

Restart Claude Desktop after saving.

## Claude API (Messages API)

When using Claude's Messages API with the MCP connector beta, pass your SolvaPay API key or a provider JWT as the `authorization_token`:

```json theme={null}
{
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://mcp.solvapay.com/mcp",
      "name": "solvapay",
      "authorization_token": "sk_sandbox_your_key_here"
    }
  ],
  "tools": [
    {
      "type": "mcp_toolset",
      "mcp_server_name": "solvapay"
    }
  ]
}
```

This requires the beta header `anthropic-beta: mcp-client-2025-11-20`. The API does not use the browser-based OAuth flow — pass the token directly.

## OpenClaw Gateway

Use the `@solvapay/openclaw` plugin to add payment tools to your OpenClaw gateway. Your AI agent can then manage SolvaPay through WhatsApp, Telegram, Discord, and any other connected channel.

Install and configure it with the plugin README:

See the [plugin README](https://github.com/solvapay/solvapay-openclaw) for full configuration options, troubleshooting, and development setup.

## Other MCP Clients

The SolvaPay MCP Server uses **Streamable HTTP**. Any MCP client that supports this transport can connect.

Use **Connect SolvaPay MCP** and select **Copy MCP endpoint**, then configure your client with:

| Property           | Value                                                                          |
| ------------------ | ------------------------------------------------------------------------------ |
| **Endpoint**       | `https://mcp.solvapay.com/mcp`                                                 |
| **Transport**      | Streamable HTTP (stateless)                                                    |
| **Authentication** | OAuth 2.0 (browser-based clients) or `X-API-Key` header (config-based clients) |

## Using Multiple Environments

Create separate MCP server entries in your client:

* `solvapay-sandbox` with your sandbox API key
* `solvapay-production` with your production API key

Both use the same endpoint — the environment is determined by your API key prefix:

| Key Prefix    | Environment | Data           |
| ------------- | ----------- | -------------- |
| `sk_sandbox_` | Sandbox     | Test data only |
| `sk_live_`    | Production  | Real data      |

## Verifying the Connection

After connecting, ask your AI assistant something simple like:

> "List my SolvaPay customers"

If the connection is working, you'll see a response from the `list_customers` tool. If your account is new, an empty list is expected.

## Troubleshooting

**"Authentication required" error**

For config-based clients (Cursor, VS Code): confirm the `X-API-Key` header is set in your MCP client configuration. For OAuth clients (Claude.ai): try removing and re-adding the connector to re-authenticate.

**"Invalid or expired secret key" error**

The API key is being sent but is not valid. Verify it in **SolvaPay Console > Settings > API Keys**. Make sure you copied the full key.

**"Invalid or expired provider token" error**

Your OAuth session has expired. Remove the connector and re-add it — you'll be prompted to sign in again.

**Tools not appearing**

Re-open your AI assistant or reload MCP settings. Some clients require a full restart.