MCP

The Popp AI Model Context Protocol (MCP) server lets AI tools (Claude Code, Cursor, Windsurf, Claude Desktop, etc.) interact with the Popp API and documentation directly from your editor or chat.

Server URL: https://docs.joinpopp.com/mcp

What you can do

Once connected, the AI agent has access to:

• Curated action tools — e.g. list-conversations, which return a ready-to-run recipe for a specific Popp API workflow.
• Organization tools — list-organizations shows every organization your API key can access, and select-organization tells the agent how to pick or switch the active organization.
• execute-request — runs any Popp API call on your behalf.
• search, list-endpoints, search-endpoints, get-endpoint — explore the API and its documentation.

Before you start: credentials

The MCP server calls the Popp API on your behalf, so every request must be authenticated with two headers:

You supply both in your MCP client config (below). If you don't have an API key yet, contact your Popp account manager or generate one from the Popp dashboard. If your API key can access more than one organization, x-organization-id is simply the default — see Working across multiple organizations.

Keep your API key secret. Treat any config file that contains it as a credential — don't commit it to version control.

Configuration by client

claude mcp add-json popp-api '{
  "type": "http",
  "url": "https://docs.joinpopp.com/mcp",
  "headers": {
    "x-api-key": "YOUR_API_KEY",
    "x-organization-id": "YOUR_ORGANIZATION_ID"
  }
}'

{
  "mcpServers": {
    "popp-api": {
      "type": "http",
      "url": "https://docs.joinpopp.com/mcp",
      "headers": {
        "x-api-key": "YOUR_API_KEY",
        "x-organization-id": "YOUR_ORGANIZATION_ID"
      }
    }
  }
}

{
  "mcpServers": {
    "popp-api": {
      "url": "https://docs.joinpopp.com/mcp",
      "headers": {
        "x-api-key": "YOUR_API_KEY",
        "x-organization-id": "YOUR_ORGANIZATION_ID"
      }
    }
  }
}

{
  "mcpServers": {
    "popp-api": {
      "serverUrl": "https://docs.joinpopp.com/mcp",
      "headers": {
        "x-api-key": "YOUR_API_KEY",
        "x-organization-id": "YOUR_ORGANIZATION_ID"
      }
    }
  }
}

{
  "mcpServers": {
    "popp-api": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://docs.joinpopp.com/mcp",
        "--header",
        "x-api-key:YOUR_API_KEY",
        "--header",
        "x-organization-id:YOUR_ORGANIZATION_ID"
      ]
    }
  }
}

Working across multiple organizations

A single Popp API key can access more than one organization. If you are an organization-group admin, that is every organization in your group; otherwise it is the organizations you are a member of. One connection can work across all of them — no need to reconfigure or swap credentials.

• The x-organization-id in your config is your default (active) organization — the one that organization-scoped requests target unless you choose another.
• Ask the agent to list your organizations and it calls list-organizations, which is authenticated by your API key alone (it does not need an organization selected), and shows each organization's name and id.
• To switch, just tell the agent, for example "switch to Popp Demo". It confirms the target and uses that organization's id as x-organization-id for the rest of the session. No reconnect or config change is needed.

You can only act on organizations your API key can access, and list-organizations is the definitive list. A switch lasts for the current session; a new session starts from your config default until you choose again.

Verifying the connection

Restart (or reconnect) your client, then ask the agent something like "List my most recent Popp conversations." If it returns live data, the server and your credentials are working.

Troubleshooting

• Missing Security Schemes error — the x-api-key and/or x-organization-id headers didn't reach the API. Double-check both are set in your config.
• A newly added tool isn't showing up — clients cache the tool list on connect. Restart the client or reconnect the server to refresh it.
• "Not authorized" on an organization — your API key can only act on the organizations returned by list-organizations. Ask the agent to list them and pick one from that set.
• Claude Desktop won't connect — confirm Node.js is installed and you're using the mcp-remote bridge config above, not the plain url form.