Connect an AI agent

SuperPenguin's remote MCP server lets your own AI agent investigate your organization's AI spend without copying reports into a chat.

Building a custom HTTP integration instead? Use the OAuth-authenticated Agent API. MCP and REST share the same operation contracts and authorization boundary.

Connection details

• Server name: superpenguin
• Transport: Streamable HTTP
• MCP endpoint: https://app.superpenguin.ai/api/mcp
• Authentication: OAuth 2.1 with PKCE
• API key or client secret: none

Add the endpoint to an MCP client and start its connect or login flow. SuperPenguin opens in your browser. Sign in, choose the organization you want the agent to use, review the requested read scopes, and approve the connection.

The connection inherits your current SuperPenguin membership and role for the organization you select. It does not bypass plan or feature permissions. To use another organization, create a separate connection and choose that organization during OAuth.

Give these instructions to an agent

You can paste this into an AI agent that can configure remote MCP servers:

Read https://superpenguin.ai/llms.txt, then connect a remote Streamable HTTP MCP server named superpenguin at https://app.superpenguin.ai/api/mcp. Use the server's OAuth flow; do not ask me for an API key or client secret. Pause while I sign in, choose my SuperPenguin organization, and approve access. After connecting, call get_context first, use discover to find the smallest relevant operation, and use query only with an operation returned by discovery.

If the agent cannot change its own MCP configuration, use the client-specific instructions below.

Claude Code

Add the server for your user, then launch OAuth:

claude mcp add --transport http --scope user superpenguin https://app.superpenguin.ai/api/mcp
claude mcp login superpenguin

After approval, start or resume Claude Code and ask a spend question. Run claude mcp get superpenguin if you need to inspect connection status.

Cursor

Add this entry to ~/.cursor/mcp.json for personal use across projects, or to .cursor/mcp.json for a project-scoped connection:

{
  "mcpServers": {
    "superpenguin": {
      "url": "https://app.superpenguin.ai/api/mcp"
    }
  }
}

Enable the server in Cursor's MCP settings and complete the OAuth prompt. Cursor CLI users can then run agent mcp login superpenguin if authentication is still required.

ChatGPT

Custom MCP apps require a ChatGPT plan and workspace role that supports developer mode.

1. Enable developer mode in Settings → Apps → Advanced settings, or begin from Workspace settings → Apps → Create if you are an administrator or owner.
2. Create a custom app named SuperPenguin with the endpoint https://app.superpenguin.ai/api/mcp and OAuth authentication.
3. Scan tools, complete the SuperPenguin authorization prompt, and finish creating the app.
4. Select or mention the SuperPenguin app when asking a question that needs fresh spend data.

How agents should use the server

The server deliberately exposes three small tools instead of loading every spend schema into the model's context:

1. Call get_context once to confirm the selected organization, granted access, supported workflows, time basis, and data caveats.
2. Call discover with the user's question or a workflow ID. It returns only the relevant operations, complete schemas, and examples.
3. Call query with an operationId returned by discover. Do not invent operation IDs.

For a durable analytics query, submit once and keep the returned query handle. Follow the response's retry timing and resume that same handle; never submit duplicate jobs just to poll.

For ordinary questions about spend, cost, or usage, use the understand_usage workflow. These words mean SDK and OpenTelemetry-observed token usage priced by SuperPenguin. Use reconcile_billing only when the person explicitly asks about provider bills, invoices, or reconciliation.

For Cursor, Claude Code, or Codex totals and contributors, call coding.usage_summary once. Do not list sessions and call coding.session_spend repeatedly to calculate a total. Session operations are for an explicitly selected session only. Use Analytics SQL when a first-class operation cannot express the question.

Treat missing or incomplete cost as unknown, not zero. Keep provider billing, SDK and OpenTelemetry usage, pending coding estimates, and API-equivalent coding value separate when the result distinguishes them.

High-value questions

• How much SDK or OpenTelemetry-observed AI usage did we spend today?
• What did we spend over the last seven days, and how did that change from the preceding seven days?
• Which workflow, provider, or model is driving the increase?
• Which existing optimization is supported by the evidence, and what should we investigate first?
• What was my Cursor usage this week, and which people, projects, models, or sessions drove it?
• How much observed usage value was associated with one specific Cursor, Claude Code, or Codex session?
• Which employees are connected, and which access or setup facts could explain why someone cannot use a feature?
• Are any provider connections stale, failing, or missing recent billing data?
• Which SDK API keys appear inactive or unhealthy without revealing their secret values?

Security and connection management

The OAuth grant is bound to the signed-in user, selected organization, client, and approved scopes. SuperPenguin checks current membership and permissions again when tools run. Customer secrets and full API keys are never returned through MCP.

You can review or revoke agent connections from SuperPenguin agent connections. Revoking a connection invalidates its access and refresh tokens.