MCP server, CLI and agent skills

There are two MCP servers with the same tools: a hosted one at https://api.insightsocial.app/mcp, which needs nothing installed, and a local one in the official insightsocial npm package, which is also a CLI. The agent skill teaches your agent how to use either. The package and the skill are open source under the InsightSocial GitHub organization. You do not need any of them to use the API, which is plain HTTPS (see Using an AI agent), but they save your agent from writing its own HTTP client and keep large responses out of its context.

Hosted MCP server

In Claude (desktop, claude.ai, Cowork), ChatGPT or any client that supports sign-in, add a connector with the URL https://api.insightsocial.app/mcp, click Connect, sign in to InsightSocial and click Allow. The app gets its own key, listed under Connected apps on API keys, where you can disconnect it. Step-by-step for each app is on Connect.

A client that cannot sign in can send your API key as a Bearer token instead:

{
  "mcpServers": {
    "insightsocial": {
      "url": "https://api.insightsocial.app/mcp",
      "headers": { "Authorization": "Bearer $INSIGHTSOCIAL_API_KEY" }
    }
  }
}

claude mcp add --transport http insightsocial https://api.insightsocial.app/mcp --header "Authorization: Bearer $INSIGHTSOCIAL_API_KEY"

It has the tools listed under MCP server below, with three differences: results are kept on our side for 3 days instead of on your disk, read_result reshapes them with fields, max items or an outline but not jq, and there are two more tools, quote_endpoint (the exact price of a call before you make it, free) and send_feedback (tell us about a missing endpoint or field). call_endpoint is marked as a tool that spends, so clients ask before running it. Get a key at insightsocial.app/portal/api/keys.

One command

npx -y insightsocial init

init signs you in through your browser and saves a key for this machine to ~/.insightsocial/config.json, installs the agent skill into the agents it finds, and writes or prints the MCP config. Signing in opens a sign-in page and prints a short code: type the code on the page and click Allow. The CLI then prints which account it signed into. Nothing to copy or paste. To use a key you already have, run npx -y insightsocial login --api-key isk_live_…. New accounts include 10 free calls.

MCP server

The local server runs over stdio and reads the key that insightsocial login (or init) saved, so your MCP config holds no secret.

claude mcp add insightsocial --scope user -- npx -y insightsocial mcp

{
  "mcpServers": {
    "insightsocial": { "command": "npx", "args": ["-y", "insightsocial", "mcp"] }
  }
}

You can pass INSIGHTSOCIAL_API_KEY in the server's env instead of saving it. Without a key, searching and describing endpoints still work. The server is listed in the official MCP Registry as app.insightsocial/insightsocial.

Because every result is saved in full and re-read with read_result, a 50 KB page of comments never has to sit in the model's context, and reading it again costs nothing.

Agent skill

The skill teaches an agent the workflow: search, price, call, page. It also covers when a call is free and when to stop and ask before spending. It uses the MCP server when it is connected and falls back to the CLI or plain REST when it is not.

npx skills add insightsocial/skills

claude plugin marketplace add insightsocial/skills
claude plugin install insightsocial@insightsocial

gemini extensions install https://github.com/insightsocial/skills

CLI

The same package works from a terminal or a script. Results are saved under ./.insightsocial/, so you can reshape them later without paying again.

npx -y insightsocial search instagram followers
npx -y insightsocial describe /v1/instagram/profile
npx -y insightsocial run /v1/instagram/profile -p handle=natgeo
npx -y insightsocial view --last --jq '.data.author | {username, followers}'
npx -y insightsocial credits

search, list, describe, view and credits are free. run costs the endpoint's price and prints the exact command for the next page when there is one. Each page is a separate charged call.

OpenAPI spec

To generate a client or your own agent tools, use the OpenAPI 3.1 spec. It is live and keyless at https://api.insightsocial.app/v1/openapi.json, and a copy synced daily from the live API is at github.com/insightsocial/openapi.

Next steps