FAQ

Frequently asked questions about the SolvaPay MCP Server.

​

General

How many tools are available?

See the Tools page for the current list.

What AI assistants are supported?

Any assistant that supports the Model Context Protocol with Streamable HTTP transport. This includes Cursor, Claude Desktop, Windsurf, and others. See Installation for setup instructions.

Is my data isolated?

Yes. Every tool call is scoped to the provider account associated with your credentials. You cannot access another provider’s data.

​

Authentication

What authentication methods are supported?

The MCP server supports two authentication methods:

• OAuth login — The default, for Claude.ai, Claude Desktop, Cursor, VS Code, and other clients that support remote MCP servers. You sign in with your SolvaPay Console credentials (email code, Google, or GitHub) and authorize the connection. No API key needed. OAuth sessions use the environment your account is in.
• API key — For clients that can’t open a browser (the Claude Messages API, scripts, CI). Pass your secret key in the Authorization: Bearer <secret key> header. The MCP server doesn’t read X-API-Key.

Can only existing providers connect?

Yes. The OAuth flow only allows sign-in — it does not create new accounts. You must already have a SolvaPay provider account to connect.

Which environment does the MCP server use?

The one your account is in. A new account starts in sandbox. When you switch between sandbox and production in SolvaPay Console, the next tool call uses the new environment, with no need to reconnect. Each tool result starts with an Environment: sandbox or Environment: live line (live is production), and the get_environment tool returns it on its own.

Can I use both sandbox and production keys?

Not at the same time. A key only works while your account is in its environment: sk_sandbox_ in sandbox, sk_live_ in production. A key for the other environment is rejected with a message that names the key to use. To move between environments, switch in SolvaPay Console, then update the key in your configuration. With OAuth you don’t need to change anything. See Use an API key instead.

What happens if my API key is compromised?

Revoke the key immediately in your SolvaPay Console under Developers > API Keys, then generate a new one and update your MCP configuration.

What happens if my OAuth session expires?

Sessions last up to 24 hours. Tool calls then fail with “Invalid or expired access token”. Reconnect SolvaPay in your client. You’ll be redirected to the SolvaPay login page to sign in again. You don’t need to remove and re-add the connector.

​

Technical

What transport does the MCP server use?

Streamable HTTP. The server operates in stateless mode — every request is independently authenticated. No sessions or cookies are required.

Is there a rate limit?

Rate limits depend on your plan. If a customer’s usage limits are exceeded, the check_limits tool will indicate this and can provide a checkout URL for the customer to upgrade.

What happens if the server is down?

Tool calls will fail with a connection error. The SolvaPay MCP Server runs on Google Cloud with multiple replicas for high availability. Check status.solvapay.com for service status.

Are requests encrypted?

Yes. All communication between your MCP client and the SolvaPay server uses HTTPS (TLS 1.2+).

​

Error Handling

What does a tool error look like?

Failed tool calls return a JSON error:

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Customer with reference cus_INVALID not found"
  }
}

What are the common error codes?

Code	Description
NOT_FOUND	The requested resource does not exist
VALIDATION_ERROR	Invalid or missing parameters
UNAUTHORIZED	Invalid or expired credentials (API key or OAuth token)
INTERNAL_ERROR	Server-side error — retry or contact support