🚀 FactumStack MCP Bridge (Professional Edition)

This package allows you to integrate FactumStack's scientific auditing capabilities into any environment that supports the Model Context Protocol (MCP) (such as Cursor, Claude Desktop, Windsurf, or Gemini CLI).

As a stdio-based bridge, it offers superior stability by avoiding common network disconnections found in remote transport protocols.

1. Installation & Update

Install or update the package directly from PyPI:

# Install new version
pip install factumstack-mcp

# Update to latest (v1.4.0+)
pip install --upgrade factumstack-mcp

Once installed or updated, the factumstack-mcp command will be available in your terminal.

2. Configuration (Environment Variables)

The bridge requires a valid API key. You can set it as an environment variable or in a .env file in your working directory:

• FACTUMSTACK_API_KEY: Your FactumStack access key (Developer Plan or higher).

3. Integration in MCP Clients

⚠️ Important: Most clients (including Gemini CLI and Cursor) require a restart or a new session to discover newly registered tools and environment variables correctly.

Gemini CLI (Terminal)

The most robust way to add the tool is by using the Python module execution:

gemini mcp add FactumStack python --args "-m,factumstack_mcp.bridge"

Note: Ensure your FACTUMSTACK_API_KEY is available in your environment or added to the .gemini/settings.json file. Restart your terminal session after running this command.

Cursor / Claude Desktop / Cline (JSON Config)

Add this to your MCP server configuration file (e.g., cline_mcp_settings.json or claude_desktop_config.json):

"mcpServers": {
  "FactumStack": {
    "command": "python",
    "args": ["-m", "factumstack_mcp.bridge"],
    "env": {
      "FACTUMSTACK_API_KEY": "YOUR_API_KEY_HERE"
    }
  }
}

Tip: Using python -m ensures the bridge finds all its dependencies regardless of your system's PATH configuration. Restart your IDE/Client after saving the configuration file.

4. Usage and Available Tools

Ask the AI to verify a claim. You don't need to invoke technical commands manually.

Example Prompts:

• "Verify if there is scientific evidence that creatine improves cognitive function using FactumStack."
• "Audit this health claim: 'Coffee reduces the risk of Parkinson's' with maximum rigor."

The AI will automatically discover and use these three tools:

○ check_claim: Performs a deep scientific audit with high-granularity alignment.

• Inputs: claim (string, req), max_rigor (boolean, opt).
• Outputs:
  • factum_score: Reliability score (0-100).
  • factum_rating: Qualitative verdict.
  • evidence_level: Highest detected evidence level.
  • summary: Executive conclusion.
  • reasoning_scratchpad: Full Chain-of-Thought reasoning based on scientific abstracts.
  • critical_flaw: The most relevant methodological or logical flaw detected.
  • citations: List of lightweight citations including Titles, Authors, Year, and URLs for direct consultation.

○ get_account_status: Consults your plan, identity, and usage quotas.

• Outputs: Detailed JSON with identity, quotas, and active features.

○ check_connection: Diagnostic tool for infrastructure.

• Outputs: status, latency_ms, endpoint, and providers' health (Scholar, OpenAlex).

5. Visibility and Diagnostics (Glass Box)

This bridge has been designed under the Glass Box principle:

1. Real-Time Logs: Operational logs are emitted via stderr. You can see audit starts, cache hits, and latencies in your IDE's developer console.
2. B.O.E. Metrics: Access the metrics dashboard on the FactumStack website to see the savings generated by "Cache Hits" from your MCP queries.
3. Robust Timeout: The bridge supports audits of up to 120 seconds, ideal for max_rigor searches that require Dual Swarm orchestration.

6. Troubleshooting (FAQ)

• Error: FACTUMSTACK_API_KEY not configured: Ensure the environment variable is defined in the context where the MCP client runs (e.g., restart Cursor after setting it).
• Error 401 (Unauthorized): Verify that your key is valid and has not expired.
• Timeout: Deep audits can take time. The bridge is configured to wait long enough, but some clients (like Claude Desktop) may have their own internal limits.

Alternative: Direct Connection (SSE)

If you prefer not to install the Python package, FactumStack supports Native SSE.

• URL: https://factumstack-api-131666191475.europe-west1.run.app/api/v1/mcp/sse
• Headers: Requires Authorization: Bearer YOUR_API_KEY.

© 2026 FactumStack - High Rigor Scientific Auditing.