Installation

Connect the SolvaPay MCP Server to your AI assistant.

​

Connect from this page

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

Property	Value
Endpoint	https://mcp.solvapay.com/mcp
Transport	Streamable HTTP (stateless)
Authentication	OAuth 2.0 — sign in with your SolvaPay account

You don’t need an API key. Add the endpoint to your client, and the client opens the SolvaPay sign-in page the first time it connects. Sign in with your SolvaPay provider account (email code, Google, or GitHub) and click Authorize. Only existing SolvaPay providers can connect; no new account is created during this flow.

The connection works on the environment your account is in: sandbox for a new account, production once you switch in SolvaPay Console. Switching takes effect on the next tool call, without reconnecting. From a client that can’t open a browser, use an API key instead.

​

Cursor IDE

Add SolvaPay to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json in your project root:

~/.cursor/mcp.json

{
  "mcpServers": {
    "solvapay": {
      "url": "https://mcp.solvapay.com/mcp"
    }
  }
}

1. Save the file. If mcp.json already has an mcpServers object, add the solvapay entry to it.
2. Open Cursor Settings > MCP. Cursor shows that solvapay needs sign-in; click to authenticate.
3. Sign in with your SolvaPay account in the browser window and click Authorize.

You can also use Connect SolvaPay MCP > Install in Cursor above, which writes the same entry.

After setup, SolvaPay tools are available in Cursor chat.

​

VS Code

Add SolvaPay to .vscode/mcp.json in your workspace, or to your user mcp.json (MCP: Open User Configuration):

.vscode/mcp.json

{
  "servers": {
    "solvapay": {
      "type": "http",
      "url": "https://mcp.solvapay.com/mcp"
    }
  }
}

1. Save the file.
2. Run MCP: List Servers and start the solvapay server.
3. When VS Code asks to authenticate, sign in with your SolvaPay account in the browser and click Authorize.

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

Add SolvaPay as a connector, the same way as in Claude.ai. Claude Desktop signs you in with OAuth, so you don’t need an API key.

1. Open Settings > Connectors.
2. Click Add custom connector and enter https://mcp.solvapay.com/mcp.
3. Sign in with your SolvaPay provider account and click Authorize.

Don’t add SolvaPay to claude_desktop_config.json. That file is for local servers that Claude Desktop starts itself, not for remote servers like https://mcp.solvapay.com/mcp.

​

Claude API (Messages API)

The Messages API can’t open a browser, so it can’t use the OAuth sign-in. Pass a SolvaPay secret key as the authorization_token instead (see Use an API key instead):

{
  "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 for full configuration options, troubleshooting, and development setup.

​

Other MCP Clients

The SolvaPay MCP Server uses Streamable HTTP and the standard MCP authorization flow (OAuth 2.0 with PKCE and dynamic client registration). Any MCP client that supports remote servers with OAuth can connect: add https://mcp.solvapay.com/mcp and sign in when prompted.

​

Use an API key instead

Use a secret API key only when your client can’t open a browser, such as the Claude Messages API, CI jobs, or scripts. Everywhere else, OAuth is simpler and follows your account’s environment.

Get a key from SolvaPay Console > Developers > API Keys and send it in the Authorization header. Use the key for the environment your account is in: sk_sandbox_ while it’s in sandbox, sk_live_ once you’ve switched to production. A key for the other environment is rejected, so after you switch in SolvaPay Console, replace the key in your configuration.

{
  "mcpServers": {
    "solvapay": {
      "url": "https://mcp.solvapay.com/mcp",
      "headers": {
        "Authorization": "Bearer sk_sandbox_your_key_here"
      }
    }
  }
}

The MCP server only reads Authorization: Bearer. An X-API-Key header is ignored. Keep keys out of shared or committed config files.

​

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.

Each tool result starts with an Environment: sandbox or Environment: live line (live is production). To check the environment without listing anything, ask your assistant to call get_environment.

​

Troubleshooting

“Authentication required” error

Your client connected without signing in. Reconnect SolvaPay in your client to restart the sign-in. If you use an API key, check that it’s sent as Authorization: Bearer <secret key>; an X-API-Key header is ignored and gives this error.

“Invalid or expired access token” error

The server couldn’t verify your credentials. With OAuth, your session has expired; sessions last up to 24 hours. Reconnect SolvaPay in your client to sign in again. With an API key, the key isn’t valid: verify it in SolvaPay Console > Developers > API Keys, check that you copied the full key, and check that it hasn’t been revoked.

“This is a sandbox secret key, but your SolvaPay account is in live mode” error

Only applies when you use an API key. The server returns 403 because the key belongs to the other environment. Your account was switched to production, but the configuration still sends a sandbox key. The full message names the key to use:

This is a sandbox secret key, but your SolvaPay account is in live mode. Use your live secret key (sk_live_…), or switch the account back to sandbox in the SolvaPay Console.

Replace the key with one for the account’s current environment, or switch the account back in SolvaPay Console. The same applies the other way round, to a production key while the account is in sandbox.

“Invalid or expired provider token” error

Your OAuth session has expired. Reconnect SolvaPay in your client, and 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.