How We Built an Instagram MCP Server for AI Agents (and 3 Bugs It Found)

An Instagram MCP server for AI agents is a tool endpoint — built on the Model Context Protocol — that lets Claude, ChatGPT, or Cursor pull a public Instagram account's posts and Reels as structured data instead of scraping a rendered page. InstaSeer's version is a stateless HTTP endpoint at /mcp, billed per post like the rest of the product. We shipped it, watched a real agent run a research job against it, and found three bugs that only showed up once something other than a human was reading the output.

Why Build an Instagram MCP Server for AI Agents

Marketers already ask InstaSeer to compare competitors' Instagram posts and Reels through the web dashboard. Increasingly, they ask an AI agent to do the same research inline — "pull the last month of posts from these three run-shoe brands and summarize what's working." An agent can't click through a dashboard, but it can call a tool if one exists. That's the gap MCP fills.

The Instagram competitor analysis tool and the MCP server read from the same underlying public dataset. A person gets a rendered report; an agent gets JSON. Neither one sees anything the other can't — the MCP server just skips the HTML.

How the InstaSeer MCP Endpoint Is Built

The endpoint is a single POST /mcp route speaking Streamable HTTP, the transport MCP uses for stateless request/response calls over plain HTTP instead of a persistent socket. Each request carries a bearer API key tied to a credit balance, and each returned post costs about one credit — the same unit the web app spends when a person pulls a report.

Statelessness was a deliberate choice, not a default. A stateful session would need the server to remember an agent's place between calls, which adds a class of bugs (stale sessions, orphaned state) we didn't want to own for a v1. A single request that returns everything the caller asked for is simpler to reason about, simpler to cache, and simpler to debug when something goes wrong.

The first internal test looked fine. We called the tool with a handle and a small max_posts value, got back clean JSON, and moved on. The real test came a few weeks later, when an agent ran an unsupervised research job against it — pulling a larger batch, chaining several calls, and treating every response as ground truth. That's when the contract started leaking.

Bug 1: The Result Silently Sliced to 100 Posts While Billing for 250

An agent requested 250 posts across a handful of handles and got back exactly 100 posts per handle — with no error, no truncation flag, and a bill for the full 250. The compactor layer had its own hard cap on array size, added months earlier for a completely different reason, and it applied silently underneath the MCP tool's declared max_posts parameter.

A person using the dashboard would notice a short result on sight. An agent doesn't scroll — it counts. If the tool says "returning results for max_posts: 250" and hands back 100 items, the agent has two bad options: trust the count and draw conclusions from an incomplete sample, or re-request and discover it can't tell the difference between "there are only 100 posts" and "the server stopped early." Agents generally can't page through a truncated MCP result the way a person pages through search results — there's no scroll position to resume from, just a tool call that either returns everything or silently doesn't.

The fix was to make max_posts and the compactor's cap the same number, enforced in one place, and to charge only for what's actually returned. If a request would exceed what the server can return in one call, the response says so explicitly instead of quietly truncating.

Bug 2: Every Post Had an Empty URL and Timestamp

The second bug was worse, because it passed every existing test. The MCP compactor — the layer that turns raw scrape output into the JSON schema the tool returns — read field names like post_url and taken_at, while the scrape pipeline had, at some point, started emitting permalink and timestamp. Every post came back with a real caption and real engagement counts, and a blank URL and blank date sitting right next to them.

Tests missed it because the compactor's fixtures were hand-written months earlier, in the old field shape, and nobody had regenerated them against a live scrape since. A hand-written fixture only tests that your code agrees with your assumptions — it can't catch your assumptions drifting away from the real upstream shape. The mismatch shipped clean, passed CI, and only surfaced when an agent tried to cite a source post and had nothing to point to.

That mattered more here than it would in most tools. The entire premise of InstaSeer's reports — and the reason the methodology for public social competitor analysis insists on it — is that every claim traces back to a link on a real public post. An agent doing research work for a client needs that same link to cite its source. A caption and a like count without a URL is a claim nobody can verify.

The fix was two parts: map the compactor's field reads to the scrape pipeline's actual output names, and replace the hand-written fixtures with ones generated from a live scrape on a schedule, so the test data can't quietly drift out of sync with production again.

Bug 3: An Error Message That Told the Agent to Keep Retrying

The friendliest-looking bug did the most damage. When an upstream data provider hit a billing failure on our end, the MCP server returned a generic "temporarily at search capacity, please try again shortly" message — the same copy shown to a person on the dashboard during a brief traffic spike. For a human, that's reasonable: wait a minute, refresh, move on. For an agent running an unattended job, it read as a signal to retry.

The agent retried. Then it retried again, on a backoff schedule, treating the message exactly as designed — as a transient, retryable condition. A billing failure upstream isn't transient. No amount of waiting fixes it. The agent burned most of a research session politely respecting an error message that was, in effect, lying to it about whether patience would help.

This is the general lesson buried in the specific bug: an error message written for a human assumes a human will read the situation and decide whether to retry, escalate, or give up. An agent has no situational awareness beyond what the message says. If your error text doesn't distinguish "wait and try again" from "this will never succeed without a human," an agent will guess wrong in whichever direction costs it the most time.

The fix rotates across multiple provider tokens automatically on quota or billing errors, so a single account-level failure doesn't stall requests in the first place. Where a failure can't be masked by rotation, the error response now says explicitly whether retrying can ever succeed, instead of defaulting to a phrase built for a different audience.

What We Changed After the Three Bugs

Rather than patch each bug in isolation, we treated the recurring failure mode — a contract that held for a person but broke for an agent — as the actual problem. The table below maps each bug to its root cause and the shipped fix.

We also added a free, built-in sample profile the endpoint always serves at zero credit cost. Any agent — or any developer testing a new deploy — can call the tool against the sample handle first, confirm field names and pagination behave as documented, and only then point a paid job at a real handle. It's the same idea as a health-check endpoint, scoped to the actual tool contract instead of just "the server is up."

Lessons for Anyone Shipping an MCP Server

None of these three bugs were exotic. They were the kind of small contract mismatch that ships in most tools and stays invisible for months, because a person on the other end quietly compensates without ever filing a bug report. An agent doesn't compensate. It takes the contract literally, which is exactly what makes MCP servers a harsher testing ground than the human-facing product they're built on top of.

A few habits generalize past Instagram data specifically:

• Honor every parameter your tool schema declares — a silent internal cap on top of a documented one is a broken promise, not an optimization.
• Generate test fixtures from live upstream output on a schedule, not once by hand. A fixture that never changes eventually tests nothing real.
• Write two versions of every error message where the difference matters: what a human should do, and whether an agent should ever retry.
• Ship a free, zero-cost way to verify a deploy before anyone spends real credits finding out it's broken.
• Bill for what you return, not for what was requested — the two should be identical, but treat them as separate checks until you've proven they are.

These apply whether you're exposing Instagram data, a CRM, or an internal ticketing system through MCP. The protocol standardizes how an agent calls your tool; it does nothing to guarantee your tool tells the truth about what it did.

What the MCP Server Does and Doesn't Expose

Worth stating plainly, since it's easy to assume an API implies broader access than it has: the MCP server reads exactly the same public data a person sees when they open a public Instagram profile. Posts, Reels, captions, dates, hashtags, and the engagement counts Instagram displays publicly. Nothing more.

It does not, and cannot, return private analytics, ad spend, Story views, DMs, or follower demographics — those live behind the account owner's own login, not in anything public-facing, agent or not. If an agent asks for audience quality or fake-follower scoring, the honest answer is that no public-data tool can measure that reliably, InstaSeer included; treat any tool that claims otherwise with suspicion. For a closer look at exactly what's visible on a public profile and what isn't, see our notes on public Instagram account analytics.

The same boundary applies across platforms. If an agent's research job spans TikTok or Facebook Pages too, the TikTok competitor analysis tool and Facebook Page competitor analysis tool follow the identical public-data-only rule, whether called from a dashboard or an MCP request.

How to Try the MCP Server Yourself

If you're building an agent workflow and want to see the contract before committing credits to it, start with the sample profile rather than a live handle. Confirm the response includes a URL and timestamp on every post, confirm the post count matches what you asked for, and check what the error response looks like when you intentionally send a bad API key.

Once the shape checks out, point it at a real competitor set the same way you would through the dashboard. Our Instagram competitor analysis checklist works as a review list either way — whether a person or an agent pulled the data, the same fields need to be present before you trust a conclusion built on top of them.