MCP Tool Reference

Complete reference for every tool exposed by the Flux MCP server at https://fluxgraph.app/mcp. For setup instructions, see MCP & API Access.

How it works

Every tool call uses the same JSON-RPC 2.0 envelope:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "<tool_name>",
    "arguments": {}
  }
}

Auth is a bearer token on every request:

POST https://fluxgraph.app/mcp
Authorization: Bearer flux_xxx
Content-Type: application/json

Most tools are free. Paid tools are marked with their credit cost — call get_cost_estimate before running an expensive tool to preview spend.

Universal errors

These apply to every tool call:

Per-tool error blocks below only list errors specific to that tool.

Analytics

Query your own post history — KPIs, trends, patterns, and search.

get_posts

Return posts with full metrics and text content for a tracked profile. Supports filtering by date range, post type, minimum engagement, and text search. Pass scope to restrict to a collection. Paginated.

Input

Returns: posts array with id, metrics, text content; meta with pagination info.

get_profile_summary

KPI summary for a tracked profile: total posts, avg engagement (likes/comments/shares/conversation rate), posts per week, engagement trend, top format, and posting goal status.

Input

Returns: total_posts, avg_engagement, avg_likes, avg_comments, avg_shares, conversation_rate, posts_per_week, engagement_trend, top_format, posting_goal.

get_posting_insights

Optimal posting patterns: best day of week, best hour, format performance breakdown, character-length sweet spot. All metrics relative to the user's own baseline.

Input

Returns: best_day, best_hour, best_format, sweet_spot_length, plus full breakdown arrays by day/hour/format/length.

Errors: 403 — Profile or scope not found/not owned.

get_engagement_trends

Engagement time series with gap-filled buckets, rolling averages, and trend direction. Each bucket includes avg engagement, likes, comments, shares, and conversation rate.

Input

Returns: series array with per-bucket metrics and rolling averages; summary with direction and change_pct.

get_topic_insights

Top terms and bigrams across a profile's posts, ranked by post count and engagement vs baseline. Each term carries a sample post URL. Pass scope to recompute against a collection.

Input

Returns: terms array (term, post_count, avg_engagement, vs_baseline, sample_post_url); bigrams array; total_posts.

search_posts

Search posts by keyword and/or semantic similarity. Full-text search with stemming for keyword matches, pgvector embeddings for semantic matches.

Input

Returns: posts array with matched posts (similarity scores in semantic modes); meta with query, mode, result_count.

Errors: 400 — Query required, or embedding generation failed. 403 — Profile or scope not found/not owned.

find_similar_posts

Find posts semantically similar to input text using OpenAI embeddings and pgvector cosine similarity. Scope to a profile or collection.

Input

Returns: posts array sorted by similarity; count.

Prediction & drafting

Score drafts before you publish and generate fresh angles grounded in your top performers.

score_draft

Predict how a draft post will perform against historical data. Returns predicted engagement percentile, projected range, factor breakdown, similar past posts, and improvement suggestions. Uses the same model as the Score My Post page.

Input

Returns: percentile (0–100), stars (qualitative band), range (low/high projected engagement), factors array, similar_posts, suggestions, model metadata (sample size, R², calibration).

Errors: insufficient_data — Not enough historical posts to train; no charge.

suggest_angles — 5 credits

Given a topic, suggest 5 distinct content angles informed by what performs well in your scoped data. Pulls top historical posts as context and uses OpenAI to generate angles.

Streams

Always-on research streams — external profiles, companies, topics, hiring signals, ad watches — that pull on a schedule into your library.

list_profiles

List all tracked LinkedIn profiles for the authenticated user. Returns profile IDs needed by other tools.

Returns: profiles array (id, display_name, linkedin_url, plan_type, status, posting_goal_per_week, autopilot_active).

list_streams

List all research streams. Pass type to filter.

Input

Returns: streams array with id, type, name, source_url, schedule, active, credits_per_run, last/next run.

create_stream

Create a new research stream. The create call itself is free; each scheduled run costs credits per stream type. own_profile streams come from subscription checkout, not this tool.

get_stream_feed

Return the most recent posts a stream has collected, newest first by published_at.

Input

Returns: stream info; posts array.

Errors: 404 — Stream not found or not owned by you.

pause_stream

Pause a stream so it stops running on its cron schedule. Existing posts remain in the library.

Input: stream_id (required).

resume_stream

Resume a paused stream. Queues it to run on the next cron tick.

Input: stream_id (required). Returns: next_run_at.

delete_stream

Delete a stream and its runs. Posts it collected stay in your library. own_profile streams can't be deleted here — cancel the subscription instead.

Input: stream_id (required).

Errors: 403 — own_profile streams cannot be deleted.

run_stream_now — 1–2 credits

Manually trigger a stream run instead of waiting for its cron tick. Charges 1 credit/run for most types, 2 for person_interests.

Collections & Segments

Collections group posts; segments group people. Both can be smart (predicate-driven) or manual.

list_collections

List all post collections, with member counts.

Input: Optional type filter (manual, smart, auto_stream).

Returns: collections array with id, name, type, config, stream_id, member_count.

create_collection

Create a new post collection. Manual or smart (predicate-based).

Input

add_to_collection

Add one or more posts to a collection. Existing members are silently ignored.

Input: collection_id (required), post_ids array (1–1000 per call).

Returns: added, skipped, member_count.

remove_from_collection

Remove one or more posts from a collection. Missing members are silently ignored.

Input: collection_id (required), post_ids array (1–1000 per call).

Returns: removed, not_found, member_count.

resolve_collection

Resolve a collection into a concrete list of post_ids. Works for both manual and smart collections.

Input: collection_id (required), limit (default: 1000, max 5000).

Returns: post_ids array, count, warnings (predicate-evaluation warnings).

list_segments

List all audience segments with member counts. Segments are named groups of people (e.g. "ICP — VPs of Marketing", "Champions").

Input: Optional type filter (manual, smart, auto_stream).

create_segment

Create a new audience segment. Manual or smart (template-based).

Input

add_to_segment / remove_from_segment

Add or remove people by person_id. Accepts 1–1000 per call. Returns added/removed, skipped/not_found, and updated member_count.

resolve_segment

Resolve a segment into a concrete list of person_ids.

Input: segment_id (required), limit (default: 1000, max 5000).

list_segment_templates

List available smart-segment templates. Pass a template id to create_segment to spin up a preconfigured segment.

save_post — 1 credit

Save a LinkedIn post to your library by URL. Resolves via HarvestAPI and stores it with source_type='saved'. Optionally adds the post to a manual collection. Failed lookups don't charge.

get_alerts

Return recent alerts for your streams.

Input: unread_only (default: true), limit (default: 50, max 200).

Returns: alerts array with stream_id, stream_name, items_new, message, read_at.

Research (HarvestAPI)

On-demand lookups against LinkedIn data. Most calls cost 5 credits. Results from profile/company post pulls land in your library; per-post reactions/comments populate the engagement graph so subsequent queries about who-engages-with-what become free.

Constellation (warm outreach)

Map the graph around a target account, score warm paths, and prioritize an outreach queue.

create_campaign

Create a Constellation outreach campaign. Groups target accounts, people at those accounts, and warm connections.

Input: name (required, 1–200 chars), description (optional).

add_campaign_accounts

Add target companies to a campaign. Pass 1–500 per call with company_name, optional linkedin_company_id, employee_count, and tier.

map_constellation — up to ~175 credits

Map the professional graph around a target company. Finds senior decision-makers, pulls their recent posts/reactions/comments to identify engagers, scores every connection, and produces a prioritized outreach queue. Actual cost is reported in the response.

score_connections

Re-score all Constellation entries in a campaign and rewrite queue positions. Run after new engagers or targets are added.

Input: campaign_id (required). Returns: rescored count.

get_outreach_queue

Return the prioritized outreach queue for a campaign, sorted by composite score. Each entry includes person details, pool (coworker/engager/mutual), recommended action, and prior log entries.

Input: Exactly one of campaign_id, segment_id, or linkedin_urls (max 200). Optional limit (default: 50) and pool filter.

get_engagement_brief

For a Constellation target, return their recent posts that most closely overlap with your own posting topics, plus suggested talking points. Use before a warm comment or DM.

Input: Exactly one of target_id, person_id, or linkedin_url.

Returns: posts array with excerpt, engagement, similarity score, and talking_points.

log_outcome

Append an entry to the outreach log: connection requests, acceptances, replies, or no-responses. Feeds get_campaign_stats.

Input: campaign_id, person_id, action (sent_request, accepted, replied, no_response), optional note.

get_campaign_stats

Summary stats for a campaign: target count, outreach volume, acceptance/reply rates broken down by pool and score tier.

Engagement graph

Read-only queries against the engagement graph — people who reacted or commented on posts in your library. The graph is built up by stream runs and the paid linkedin_post_* tools.

get_post_engagers_by_company

For a post, group its engagers by current company. Filter to a single industry URN to slice tighter.

Input: post_url or post_id (one required); optional industry_urn, limit (default: 20), top_engagers_per_company (default: 3).

Returns: companies array with engager_count and top_engager names.

get_post_set_engagers — 2 credits/post + 3/enrich

Consolidated, deduped people who reacted/commented across a post set. Fetches only un-synced posts; enriches only never-seen people up to max_enrich. Cached posts are free.

Input: profile_id or collection_id (one required).

get_engagement_industry_breakdown

Histogram of engagers' industries on a post, with optional depth (1 = top-level, 3 = leaf) and sample companies per bucket.

Input: post_url or post_id (one required); depth (default: 1, range 1–3).

get_alumni_engagers

For a target company, list people who engaged with your posts and who are current employees, alumni, or both.

Input: company_url or company_id (one required); relation (coworker, alumni, any; default: any); limit (default: 20).

get_engager_position_history

Career history of a person who has engaged with your posts. Only available for actual engagers — not arbitrary LinkedIn profiles.

Input: person_id or linkedin_url (one required).

get_target_warmth_brief

Engagement summary for an engager against your posts: warmth score (0–1.0), reaction/comment counts, first and most recent engagement dates, and the posts they touched.

Input: person_id or linkedin_url (one required); days_back (default: 90, range 1–365).

get_company_engagement_overlap

People who engaged with both Company A's and Company B's posts in your library.

Input: company_a_id or company_a_url (one required each for A and B); limit (default: 20).

Returns: overlap_count, engagers_on_a_only, engagers_on_b_only, engagers array.

get_outreach_path

Find warm-intro paths to a target person via coworker/alumni edges in your engagement graph. Up to 3 hops.

Input: target_person_id or target_linkedin_url (one required); max_hops (default: 2, range 1–3); limit (default: 10 paths).

Returns: paths array with warm engager, steps, and hop count; grouped by hop count.

Graph traversal (experimental)

Run read-only SQL queries against a sandboxed view of your data.

traverse_graph_help

Returns the table schema, FK edges, your caller identifiers, example queries, and validation constraints. Call this first before writing any custom queries.

traverse_graph

Execute a single SELECT (or WITH ... SELECT) against the graph. Must reference one of your caller_user_ids or tracked_lp_ids. INSERT, UPDATE, DELETE, and DDL are blocked. Row cap: 1000; statement timeout enforced.

Input: sql (required) — must start with SELECT or WITH.

Returns: rows, row_count, generated_sql, elapsed_ms. Includes _warnings if row count was capped.

Errors: 400 — SQL contains forbidden keywords, doesn't reference caller ID, or doesn't start with SELECT/WITH.

Admin & billing

get_credit_balance

Return your current credit balance, this period's monthly allocation, and credits used since the period started.

Returns: balance, monthly_allocation (amount, plan_type, period_start, period_end), used_this_period.

get_cost_estimate

Given an MCP tool name, return its credit cost so you can preview an action before running it.

Input: tool_name (required).

Returns: cost, balance, sufficient (boolean), known_tool.

get_usage_history

Recent credit ledger transactions. Filter by tool, reason, or date range. Paginated.

Input: Optional tool_name, reason (monthly_grant, pack_purchase, tool_usage, refund, adjustment), date_from, date_to, limit (default: 50, max 200).

Returns: transactions array with amount, balance_after, reason, tool_name, created_at.