Skip to navigation
MCP

Quickstart

Paid’s MCP server lets you inspect and manage Paid resources directly from AI-powered tools like Claude Code, Claude Desktop, Cursor, VS Code, and Windsurf. Instead of switching between your editor and the Paid API docs, you can ask your assistant to list customers, inspect products, create test data, or run safe read-only checks while it already has context on the code you are building.

The hosted server accepts two kinds of credentials. Signing in with Paid is the recommended path and needs no key in your config. A Paid API key also works and suits shared or unattended setups.

Prerequisites

  • A Paid account.
  • An MCP-compatible AI tool such as Claude Code, Claude Desktop, Cursor, VS Code, or Windsurf.
  • A Paid API key, only for the API key setup described below.

The hosted server URL is:

https://mcp.agentpaid.io/mcp

Connect with single sign-on

Add the server URL with no Authorization header. On the first request your client detects that the server is protected, opens the Paid login page in your browser, and stores the resulting session itself. You never copy a credential into a config file.

Tools then run as you: with your organization role, so viewers keep read-only access, and with your name on every change recorded in the audit log.

What signing in looks like

The whole exchange is handled by your client. Adding the server is step one; signing in happens the first time the client actually talks to it.

  1. Your client requests https://mcp.agentpaid.io/mcp and gets a 401 naming Paid as the authorization server.
  2. It registers itself with Paid automatically. There is no application to create and no client id to paste.
  3. Your browser opens on auth.paid.ai. Sign in the same way you sign in to the Paid app, including through your company’s SSO if your organization uses one.
  4. Approve the access request. The screen names the client that is asking, so check it is the tool you actually started.
  5. The browser hands control back to your client, which stores the session and retries the original request.

From then on the client refreshes its own access silently. The browser opens again whenever that saved access can no longer be refreshed, for example after you revoke the connection, after a long gap, or on a new machine. Being asked to sign in again is normal and not a sign that something is broken.

Claude Code

claude mcp add --transport http paid https://mcp.agentpaid.io/mcp

Run /mcp in Claude Code and choose Authenticate to complete the login.

Claude Desktop

Custom connectors are available on every Claude plan, but how you add one depends on your plan.

On Free, Pro, or Max

  1. Go to Customize, Connectors.
  2. Click +, then Add custom connector.
  3. Name it Paid, or anything you will recognize later, and paste in the server URL: https://mcp.agentpaid.io/mcp.
  4. Leave Advanced settings as is. There is nothing to change there.
  5. Click Add to finish, then click Connect to sign in.

On Team or Enterprise

Adding the connector is a two-step process: an owner adds it to the organization once, then each member connects individually.

Owner setup, one time:

  1. Go to Organization settings, Connectors.
  2. Click Add.
  3. Hover over Custom, then select Web.
  4. Name it Paid, or anything you will recognize later, and paste in the server URL: https://mcp.agentpaid.io/mcp.
  5. Leave Advanced settings as is. There is nothing to change there.
  6. Click Add to finish.

Member setup, for each person who wants to use it:

  1. Go to Customize, Connectors.
  2. Find the connector the owner added. It is usually labeled Custom.
  3. Click Connect to sign in.

Cursor

Add the server to ~/.cursor/mcp.json for every project, or to .cursor/mcp.json inside a single project:

{
  "mcpServers": {
    "paid": {
      "url": "https://mcp.agentpaid.io/mcp"
    }
  }
}

Cursor shows a login action next to the server under Settings, MCP. Select it to sign in.

VS Code

Add the server to .vscode/mcp.json in your workspace:

{
  "servers": {
    "paid": {
      "type": "http",
      "url": "https://mcp.agentpaid.io/mcp"
    }
  }
}

Start the server from the Start action in that file or from the agent mode tool picker, then approve the sign-in prompt.

Windsurf

Add the server to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "paid": {
      "serverUrl": "https://mcp.agentpaid.io/mcp"
    }
  }
}

Refresh the server list in Windsurf’s MCP settings to trigger the login.

Other MCP clients

Most clients accept a JSON entry with the server URL and no credentials:

{
  "mcpServers": {
    "paid": {
      "type": "http",
      "url": "https://mcp.agentpaid.io/mcp"
    }
  }
}

Clients that cannot sign in on their own can bridge through mcp-remote, which runs the login flow locally and opens your browser:

{
  "mcpServers": {
    "paid": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.agentpaid.io/mcp"]
    }
  }
}

To connect a client you built yourself, read https://mcp.agentpaid.io/.well-known/oauth-protected-resource/mcp to discover the authorization server, run a standard OAuth 2.1 authorization code flow with PKCE and resource=https://mcp.agentpaid.io/mcp, then send the resulting access token as a bearer token on every request. Most MCP SDKs handle this for you.

Connect with a Paid API key

An API key is the better fit when nobody is present to sign in, such as a shared workstation or an automated environment. Create or copy a key from Settings, API keys, then pass it as a bearer token:

{
  "mcpServers": {
    "paid": {
      "type": "http",
      "url": "https://mcp.agentpaid.io/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_PAID_API_KEY"
      }
    }
  }
}

In Claude Code:

claude mcp add --transport http paid https://mcp.agentpaid.io/mcp \
  --header "Authorization: Bearer YOUR_PAID_API_KEY"

Requests made with an API key carry that key’s scopes, and audit entries name the person who created the key rather than the person using the assistant. Sign in instead when you want changes attributed to you.

Verify the connection

Once connected, confirm things are working by asking your assistant:

List my Paid customers.

or:

Show me my Paid products.

If your assistant answers a question about your Paid account with made-up customers, revenue, or IDs, the Paid tools almost certainly are not active for that session. Confirm the server is configured and connected, then ask again. Do not trust a response the tools did not produce.

When signing in does not work

The client never offers to sign in. It is probably reusing a cached probe from before it could reach Paid. Remove the server and add it again, which makes the client repeat the discovery step. In Claude Code that is claude mcp remove paid followed by the claude mcp add command above.

The browser reports that something went wrong. Read the client name on the error page or in your client’s log and check it matches the tool you started. If it does, the sign-in request reached Paid but was rejected; send that client name to support, since the tenant-side authorization is what needs adjusting.

Every tool call fails with a permission error. Your Paid role decides what the tools can do. Viewers can read but not write, exactly as in the Paid app. Ask an administrator of your organization to change your role if you need more.

Tools ask which organization to use. When you sign in and your Paid account belongs to more than one organization, the tools return a 400 ORGANIZATION_REQUIRED error listing your organizations in availableOrganizations. Pick the id you want and ask again, naming it in the tool call:

List Paid customers with paidOrganizationId set to <organization_id>.

API keys are not affected, since each key already belongs to one organization.

You want to sign in as someone else. Disconnect the server in your client and add it again. The next request starts a fresh login.

What you can do

Once connected, you can ask your AI assistant to:

  • Inspect Paid resources: List customers, products, plans, orders, invoices, checkouts, webhooks, pricing configurations, and value receipts.
  • Create and update test data: Create customers, draft orders, products, contacts, checkouts, and other resources while developing integration flows.
  • Record signals and costs: Send signals and cost events from examples in your codebase to validate billing and analytics behavior.
  • Debug billing flows: Check order state, invoice state, credit balances, customer portal sessions, and related resources without leaving your editor.

Next steps