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.

Claude SEO and marketing brains

If you already run the open source claude-seo plugin or one of the AI Marketing Hub brains in Claude Code, there is an extension that plugs Pengu in as their live data source. Its skills keep working exactly as before; the sections that say "if live data is available" now get it from Pengu, and /seo pengu <command> calls any tool directly.

git clone https://github.com/Pengu-Insights/claude-seo-pengu.git
cd claude-seo-pengu
bash install.sh        # Windows: .\install.ps1

The installer asks for your key without showing it, registers the server with claude mcp add, copies a seo-pengu skill and agent into ~/.claude, and adds one delimited block to ~/.claude/CLAUDE.md that routes the brain's live-data requests to Pengu. uninstall.sh reverses all of it.

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 thirty-five tools and one prompt. Their names match the REST endpoints, and their input schemas are the same, so anything documented under Resources applies here too.

GEO report

Besides tools, the server ships a prompt: a ready-made workflow you pick yourself instead of explaining it to the assistant every time. geo_report turns one brand into a client-ready report on its visibility in AI assistants.

In Claude Code type / and pick geo_report from the pengu server, or in Claude open the + menu. Fill in:

The assistant then states the plan and its cost, makes the calls, and writes the report in ten sections: an executive summary with the client's share of voice, AI visibility by model, a share of voice table against competitors, the questions where buyers meet the brand and the ones where only competitors appear, the sources shaping the answers, AI search demand for the category, Google AI Overviews, what an assistant recommends today, prioritised recommendations each tied to a finding, and the method and its limits.

A report with three competitors costs about 180 credits in the US and about 210 elsewhere. Outside the US the report measures the client's own market and adds the ChatGPT figure once, labelled as a US reference: that index only holds US English data, and comparing a Spanish brand on it would answer a different question from the one asked.

Fetching the prompt is free. The credits are spent by the tool calls that follow, and every figure in the report has to come from one of them: the prompt tells the assistant not to estimate, extrapolate or invent a number, and to say so when the evidence is thin.

Prompt support varies by client. Claude Code and Claude show them; if yours does not, ask the assistant for a GEO report of the brand and it will find the same tools on its own.

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:

• "Audit mailchimp.com and its three most linked pages, then list the fixes by score impact."
• "Take every autocomplete phrase for 'crm software' in the US, size them, and give me the ten with volume over 1,000 and difficulty under 30."
• "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 40 credits and facebook_ads at 20 ads is 20; a question that needs both for two brands costs about 120. 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