FullMention

npm version License

The FullMention MCP Server provides a secure, high-performance gateway that allows Large Language Models (LLMs) and AI agents (such as Claude Desktop, Cursor, or custom agent networks) to interact directly with the FullMention Public API.

By exposing FullMention’s stateless simulation runs as native MCP tools and structured resources, your AI models can trigger batch analysis runs, track progress, fetch results, and analyze visibility metrics seamlessly.

---

[!NOTE]

📊 Explicit Ranking System

AI recommendation results in FullMention utilize flat ranking lists (brandRankings, websiteRankings, productRankings).

• Position Order: Each item in these lists includes a position property starting at 1. Position 1 represents the top recommendation / most prominent suggestion within the LLM context, followed sequentially by lower rankings.
• Rule: The elements in these lists are strictly ordered by relevance and visibility prominence. Do not sort these arrays alphabetically, as doing so discards valuable visibility intelligence!

---

Quickstart: Connect your AI Client (Local Desktop)

To connect the FullMention MCP Server to your local editor or chat client, configure your client using the configurations below.

1. Claude Desktop Setup

Add the following configuration to your claude_desktop_config.json (typically located at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "fullmention": {
      "command": "npx",
      "args": ["-y", "@fullmention/mcp-server"],
      "env": {
        "FULLMENTION_API_KEY": "your_fm_live_key_here"
      }
    }
  }
}

[!TIP] Version Pinning: To prevent breaking changes from affecting your production workflows, consider pinning a specific SemVer version when starting via npx: "args": ["-y", "@fullmention/[email protected]"]

2. Cursor Setup

1. Open Cursor Settings and go to Features -> MCP.
2. Click + Add New MCP Server.
3. Fill in the configuration:
   • Name: FullMention
   • Type: stdio
   • Command: npx -y @fullmention/mcp-server
4. Set the environment variable FULLMENTION_API_KEY to your API key.
5. Click Save.

---

Core Architecture & Smart Shielding

The FullMention MCP Server is designed from the ground up to be AI-safe and highly resource-efficient, shielding your API quotas and credit budgets automatically:

• 🛡️ In-Memory Query Shielding: Caches query responses (60-second TTL) to protect your external API rate limits from redundant agent loops.
• 🚦 Status Polling Guardrails: Detects rapid-succession polling of active batch-run statuses. If an AI agent polls the server within 8 seconds, the server intercepts the network call and returns cached state with a [POLLED_TOO_FAST_CACHED_WARNING], saving network overhead and API stress.
• 📊 Server-Side Share of Voice: Automates brand-visibility calculation server-side with get_share_of_voice to completely prevent mathematical hallucinations in LLMs.
• 🚀 Server-Side Token Optimization: Supports a format: "markdown" parameter. Instead of sending raw verbose JSON to the LLM, the MCP server automatically compiles your data into highly compressed, dense Markdown tables, saving massive token overhead and drastically reducing your LLM input cost.

---

Exponentiate with Cloud Deployment (SSE Mode)

For SaaS and cloud architectures, the FullMention MCP Server supports SSE (Server-Sent Events) HTTP Transport dynamically out of the box.

Launching in SSE Mode:

To spin up the HTTP gateway on port 3000 (or configured PORT / FULLMENTION_MCP_PORT):

npx -y @fullmention/mcp-server --sse

100% Secure Metrics Endpoint

When hosted in SSE mode, you can inspect diagnostics and live caching performance metrics via:

curl http://localhost:3000/diagnostics

---

Detailed Tool & Parameter Reference

FullMention MCP server exposes 7 dedicated tools. Below is the complete parameter schema and response shape for each tool:

📊 System & Quota Tools

1. get_status

Retrieve dynamic system and engine status from the FullMention platform.

• Parameters: None.
• Response (JSON):

  {
    "status": "operational",
    "engines": {
      "openai": "operational",
      "openaiMini": "operational",
      "gemini": "operational"
    }
  }
  

2. get_quota

Retrieve account quota limits and current usage.

• Parameters:
  • bypassCache (boolean, optional): If set to true, bypasses the cache.
• Response (JSON):

  {
    "limit": 10000,
    "used": 2350,
    "extra": 0,
    "remaining": 7650
  }
  

3. get_usage_stats

Retrieve detailed quota and credit statistics with budget warnings.

• Parameters:
  • bypassCache (boolean, optional): If set to true, bypasses the cache.
• Response: Markdown summary of remaining credits, monthly limit, and the current credit pricing matrix.

---

🚦 Simulations & Runs

4. trigger_run

Trigger an asynchronous stateless simulation run.

• Parameters:
  • keywords (array of strings, required): List of keywords to simulate (maximum 500).
  • engines (array of strings, required): AI search engines to target (e.g. ["openai", "openai-mini", "gemini"]).
  • country (string, required): Country context (e.g., "Denmark" or "United States").
  • language (string, required): Language context (e.g., "Danish" or "English").
  • location (string, optional, nullable): Optional specific city context (e.g., "Copenhagen").
  • fanout (boolean, optional): Enable web search fanout (adds 1 credit cost per keyword).
  • webhookUrl (string, optional, nullable): Optional fully qualified HTTP/S URL to call back when the run finishes.
  • idempotencyKey (string, optional): Unique string to prevent duplicate runs.
• Response (JSON):

  {
    "id": "run_987abc",
    "status": "queued",
    "progress": {
      "status": "queued",
      "totalRequests": 10,
      "completedRequests": 0,
      "failedRequests": 0,
      "percentage": 0
    },
    "estimatedCredits": 10,
    "createdAt": "2026-06-10T22:00:00.000Z",
    "completedAt": null,
    "expiresAt": "2026-06-11T22:00:00.000Z",
    "statusUrl": "https://api.fullmention.com/v1/runs/run_987abc"
  }
  

5. get_run_status

Retrieve details, progress, and results of a run using runId.

• Parameters:
  • runId (string, required): The ID of the run.
  • format ("compact" | "raw" | "markdown", optional, default: "compact"): Response format.
  • bypassCache (boolean, optional): If true, bypasses cache.
• Response: A dense Markdown table (if format: "markdown") or a trimmed JSON representation of the run and results.

6. get_fanout_sources

Retrieve full paginated web sources and search queries for a specific recommendation result.

• Parameters:
  • runId (string, required): The ID of the batch run.
  • resultId (string, required): The result snapshot ID.
  • limit (number, optional).
  • cursor (string, optional).
• Response (JSON):

  {
    "data": [
      {
        "domain": "ahrefs.com",
        "url": "https://ahrefs.com/blog/best-seo-tools/",
        "title": "Best SEO Tools for 2026",
        "snippet": "Read our comprehensive review of top SEO suites...",
        "crawledAt": "2026-06-10T22:05:00.000Z"
      }
    ],
    "meta": {
      "nextCursor": "eyJza2lwIjoxfQ=="
    }
  }
  

7. get_share_of_voice

Calculate Share of Voice % and average ranking server-side for a completed run.

• Parameters:
  • runId (string, required): Completed run ID to analyze.
  • brands (array of strings, optional): Specific target brands for comparison.
  • format ("json" | "markdown", optional, default: "markdown").
  • bypassCache (boolean, optional).
• Response: Markdown table report or aggregated JSON with visibility percentages.

---

Exposed Native Resources

AI models can query data directly using these structured, native resources:

• fullmention://schema/openapi — Machine-readable API contract.
• fullmention://runs/{runId} — Summarized markdown report for a specific completed run.

---

AI-Guided Prompts

Predefined agent templates included in the MCP server:

• brand-analysis: Analyzes competitor occurrences in the results of a completed run.
• credit-optimization: Advises on credit costs for a planned run based on keyword and engine counts.
• gap-analysis: Analyzes keyword gaps where competitors are visible but your own brand is missing in a run.
• citation-coverage: Maps domains and web sources for a run.
• category-dominance: Shows category dominance based on AI recommendations in a run.
• executive-digest: Generates weekly executive KPI summary from a run.