MCP and Claude Code

Pengu Insights ships a remote MCP server. Point any client that speaks the Model Context Protocol at it, add your API key, and every endpoint on this site becomes a tool the model can call on its own. No install, no local process, nothing to keep running.

Claude Code

One command. Run it inside the project where you want the tools available, or add --scope user to have them everywhere.

claude mcp add --transport http pengu \
  https://suvjexogmfpvxjcktvuk.supabase.co/functions/v1/mcp \
  --header "Authorization: Bearer pk_live_YOUR_KEY"

Type /mcp inside Claude Code to confirm pengu shows as connected, then just ask. Claude reads the tool descriptions, decides which calls to make, and reports the result. The meta.credits_charged value comes back with every tool result, so you can ask it how much a task cost.

Other clients

Claude Desktop, Cursor, Windsurf, Cline and most other clients accept an HTTP server in their MCP configuration. The block is the same everywhere; only the file it lives in changes.

{
  "mcpServers": {
    "pengu": {
      "type": "http",
      "url": "https://suvjexogmfpvxjcktvuk.supabase.co/functions/v1/mcp",
      "headers": {
        "Authorization": "Bearer pk_live_YOUR_KEY"
      }
    }
  }
}

Claude Desktop only speaks stdio to local servers, so it needs the small mcp-remote bridge shown above; everything else connects to the URL directly.

Tools

The server exposes fifteen tools. Their names match the REST endpoints, and their input schemas are the same, so anything documented under Resources applies here too.

Prompts that work well

The model decides which tools to call from your question, so ask for the outcome rather than for a tool. A few that map cleanly:

• "What does hubspot.com rank for in Spain? Give me the ten keywords sending the most traffic."
• "Is there an AI Overview for 'best crm for small business' in the US, and who does it cite?"
• "Compare the organic footprint of asana.com and monday.com in the UK."
• "Find 20 keyword ideas around 'protein powder' in Mexico with difficulty under 30."
• "Which ads is Nike running right now, and how long has the longest one been live?"
• "Who are the top creators posting under #skincare on Instagram this week?"
• "Transcribe this reel and tell me the hook it uses: https://www.instagram.com/reel/XXXX/"
• "What are the most viewed YouTube videos about 'protein powder' this year, and what does the top one say in its first minute?"

Costs apply through MCP too. tiktok_search at 50 posts is 29 credits and facebook_ads at 20 ads is 18; a question that needs both for two brands costs close to 100. Each key also has a daily cap, so a runaway agent stops on its own.

How the server behaves

• Stateless. Every request carries the key and stands alone. There are no sessions to expire, which is why nothing needs to stay running on your machine.
• No server-initiated streams. The server answers POST requests and returns 405 on GET. Every client treats that as "no notifications to subscribe to" and carries on.
• Tool errors are results, not disconnects. A failed call returns isError: true with the error code and message in the text, so the model can read it and tell you. See Errors.
• Origin checked. Requests with a browser Origin header from a domain other than penguinsights.io are refused, which closes the DNS rebinding hole that remote MCP servers are otherwise open to. Native clients send no Origin and are unaffected.
• Read only. Every tool is annotated readOnlyHint: true. Nothing the model can call changes anything in your account or anywhere else.

Testing without a client

The official MCP Inspector can talk to the server from the command line, which is handy for checking a key before wiring it into an agent.

npx @modelcontextprotocol/inspector --cli \
  https://suvjexogmfpvxjcktvuk.supabase.co/functions/v1/mcp \
  --transport http \
  --header "Authorization: Bearer pk_live_YOUR_KEY" \
  --method tools/list