MCP Tools — Quick Reference

The Hypermass Media MCP exposes 30 read-only tools to any MCP-aware client (Claude Code, Claude Desktop, Cursor, Cline, custom agents). This is the "what can I ask?" reference. For protocol / auth / write tiers, see mcp-spec.md.

Connect

  1. Mint a key: dashboard → workspace → Settings → MCP API keys → Mint key. Copy the raw hyper_… value (shown once).
  2. Add to your client config:
{
  "mcpServers": {
    "hypermass": {
      "type": "http",
      "url": "https://hypermass.media/api/mcp",
      "headers": { "Authorization": "Bearer hyper_…" }
    }
  }
}
  1. Restart your client. You'll see 16 new tools prefixed by their domain (workspace.*, metrics.*, posts.*, etc.).

Every call lands in Settings → MCP API keys → Recent calls for audit.

Tools

All tools accept an optional username arg to disambiguate when the workspace has multiple IG accounts. Default = first/oldest active account. Defaults shown in ().

Workspace

Tool What it returns
workspace.get Workspace identity + connected IG accounts with followers/follows/media counts and last_synced_at. Always call first.
workspace.listMembers (OWNER only) Every workspace member with role + email + join date.

Account-level metrics

Tool Args What it returns
metrics.getCurrent username? The most-recent fully-synced day of all account-level metrics (followers, reach, views, interactions, follows/unfollows, profile views, etc.).
metrics.getPeriod days (30), username? One row per day for the last N days (max 365). Use for charts / trend analysis.
metrics.comparePeriods days (7), username? Last N days vs the N days before — sum + percent change for every core metric.

Posts

Tool Args What it returns
posts.list limit (25), media_type?, media_product_type?, username? Recent posts with core metrics. Filter by IMAGE / VIDEO / CAROUSEL_ALBUM or FEED / REELS / STORY / AD.
posts.get ig_media_id Full record for one post (long numeric Meta id).
posts.top by ("engagement"), days (30), limit (10), username? Top performers ranked by engagement / reach / views / like_count.
posts.byHashtag hashtag, limit (25), username? The workspace's own posts containing the hashtag. Leading # optional.

Audience

Tool Args What it returns
audience.demographics metric (follower_demographics), breakdown (country), username? Latest snapshot for follower_demographics or engaged_audience_demographics, broken down by age / gender / city / country. Sorted desc by value.
audience.onlineHours days (28), username? 24-hour distribution of when followers are online, averaged over the period. Use for best-posting-time recommendations.

Derived analytics

Tool Args What it returns
posting.bestTimes days (60), top_n (5), username? Cross-references when followers are online × historical engagement on Jay's posts. Ranks top hours-of-day by combined score.
engagement.byContentType days (60), username? Avg likes / comments / shares / saves / reach / engagement-rate per format (REELS vs CAROUSEL vs FEED vs IMAGE). Answers "what format wins for me."
audience.cities top_n (20), metric (follower_demographics), username? City-level demographic drill-down. Use when audience.demographics breakdown='country' is too coarse.
posts.outliers metric ("engagement"), days (90), sigma (1.5), username? Posts >= N σ above/below the account's mean. Returns hits_above and hits_below with z-score + multiple-of-mean. Use for "why did this post pop / flop?"
events.detectSpikes metric ("followers_count"), days (60), sigma (2), username? Unusual daily-metric jumps correlated with same-day posts + mentions. Surfaces "announcement day," viral reels, mention waves. For followers, uses day-over-day delta against last non-null snapshot (handles partial sync gaps).
hashtags.myPerformance days (90), min_uses (2), username? For every hashtag the account has used in its own captions: usage count + avg engagement vs the account's overall average. Surfaces "your #X posts get K× your normal."

Stories (captured by 30-min polling cron)

Tool Args What it returns
stories.list days (7), limit (50), username? Recent stories with media_type, permalink (only valid while live), timestamp, captured insights (reach, views, replies, exits, taps_forward, taps_back).
stories.insights ig_media_id Full insights for one specific story.
stories.summary days (7), username? Rollup: total stories, avg reach/views/replies, avg taps_forward (skip-rate proxy), top story by reach, completion-rate proxy (1 - exits/reach).

Stories caveat: stories vanish from Instagram after 24h. We capture them via a polling cron every 30 min, so anything posted > ~30 min before the next poll is captured with its final-state insights. The first day after deploy will have empty results until the cron has run a few cycles.

Competitor sets (storage only)

Tool Args What it returns
competitors.listSets — All named competitor sets for this workspace + their handles.
competitors.set name, handles[], description? Save / replace a named competitor list (e.g. "actor-comedians"). Pure storage — competitor fetching via business_discovery is currently blocked by our IG Login auth stack. The set persists for when we unblock the lookup ops.

Mentions, comments, brand, history

Tool Args What it returns
mentions.list limit (25), username? Recent mentions — posts where someone tagged this account. Includes tagger username, media url, like/comment counts.
mentions.get id (uuid) Full record for one mention.
comments.list ig_media_id, limit (50) Comments on one of your posts, oldest first.
comments.threadOnMyPost ig_media_id, limit (100) Same as comments.list plus a pre-built thread_map (parent → children ids) so the agent can reconstruct conversation shape without scanning.
mentions.summary days (30), username? Roll-up: total mentions, top-mentioning accounts by frequency, format breakdown, avg engagement on the mentioning post.
posts.carouselChildren ig_media_id Individual slides of a carousel post — per-slide media_url, type, metrics.
brand.get username? The workspace's BrandProfile: niche, voice, goals, off-limits topics, peer accounts, etc. Ground all recommendations in this.
history.dailyFollowers days (90), username? Follower-count snapshot per day (max 365). Use for follower-trajectory analysis.

Things to ask Claude

Once connected, natural questions work:

  • "What's my engagement trend over the last 7 days vs the 7 before?"
  • "Show me my top 5 reels from the last 90 days."
  • "What countries are most of my followers in?"
  • "What time of day are my followers online?"
  • "Who's mentioning me lately?"
  • "What's my brand profile so you can help me draft a caption?"
  • "Find my posts with #yoga and tell me which one performed best."

Claude will pick the right tool. If a question needs multiple tools (e.g. "compare this to my brand goals"), it'll chain them.

Currently blocked (was on the wish list, but Meta won't let us)

We deliberately use Instagram Business Login (cleaner UX for celebs, no Facebook Page dependency). Meta restricts a handful of cross-account endpoints to apps on the older Facebook Login for Business path. Until we add a parallel auth stack, these are unreachable:

  • competitor.profile / posts / top / compare / heatmap — needs business_discovery, returns code 100 on our auth.
  • hashtag.top / hashtag.recent — needs /ig_hashtag_search, same.
  • reel_audio_id — not exposed by any Meta API on any auth path.
  • comments_list on third-party posts — Meta only exposes comments on posts you own or that tagged you.
  • reels_trending (true trending) — no Meta API. Closest legit replacement is competitors.heatmap (blocked above) or hashtag-niche queries (blocked above).

Code for the doable-via-other-auth ones is preserved in src/lib/mcp/operations.ts inside /* DEAD */ blocks for fast revival.

Limits + safety

  • Read-only. Nothing here writes to the DB or to Instagram. Write tiers (drafts, publish) are designed in mcp-spec.md and gated behind future approval flows.
  • Workspace-scoped. A key for workspace A can't see workspace B's data — enforced at the DB layer (RLS) and re-checked in every handler that takes an id (posts.get, mentions.get, comments.list).
  • Rate-limited. 60 calls/min per key. Returns HTTP 429 with Retry-After if you blast it.
  • Audit-logged. Every call (success or error) appears in Settings → Recent calls within seconds.

Adding a new tool

Append to OPERATIONS in src/lib/mcp/operations.ts. The route picks it up automatically — tools/list will include it, tools/call will dispatch to it. Include a description that helps the LLM choose it.