{
  "markdown": "<div align=\"center\">\n  <img src=\"https://ucarecdn.com/6e7893d7-6b14-426b-83bc-574a3f72d6bc/foddaminilogo.png\" alt=\"Fodda Logo\" width=\"120\"/>\n  \n  # Fodda MCP Server\n\n  **Expert-curated knowledge graphs for AI agents** — PSFK Retail, Beauty, Sports and partner datasets via the Model Context Protocol.\n\n  [![MCP Registry](https://img.shields.io/badge/MCP_Registry-ai.fodda%2Fmcp--server-blue)](https://registry.modelcontextprotocol.io/v0.1/servers?search=ai.fodda/mcp-server)\n  [![npm](https://img.shields.io/npm/v/fodda-mcp)](https://www.npmjs.com/package/fodda-mcp)\n  [![Version](https://img.shields.io/badge/version-1.30.0-green)](./CHANGELOG.md)\n  [![License](https://img.shields.io/badge/license-Proprietary-red)](https://fodda.ai)\n\n</div>\n\n---\n\n## Quick Start\n\n### Claude (Web — Pro, Max, Team, Enterprise)\n\n1. Get your personal MCP URL at [app.fodda.ai](https://app.fodda.ai) → Account → MCP Integration (format: `https://mcp.fodda.ai/c/<your-token>`)\n2. In Claude, go to **Settings → Connectors → Add custom connector**, paste the URL, and click **Add**\n3. Start chatting with your Fodda knowledge graphs\n\n> **Note:** legacy `?api_key=` or `?user_id=` query string URLs are deprecated and return HTTP 401 with explicit instructions (`Fodda: this connection URL is outdated. Get your new MCP URL at https://app.fodda.ai...`). Get your fresh MCP URL or connect via OAuth at [app.fodda.ai](https://app.fodda.ai).\n\n\n### Claude Code (CLI — SSE)\n\n```bash\nclaude mcp add --transport sse fodda https://mcp.fodda.ai/sse \\\n  --header \"Authorization: Bearer YOUR_API_KEY\"\n```\n\n### Claude Enterprise\n\nFor Claude Enterprise with admin-managed connectors, your workspace admin can register the Fodda MCP server using the same Streamable HTTP endpoint (`https://mcp.fodda.ai/mcp`) via the Admin Console. See [Enterprise MCP Setup](./Enterprise_MCP_Setup.md) for full details.\n\n### OpenAI (Responses API — Recommended)\n\nUse OpenAI's native MCP support — no function definitions needed:\n\n```python\nfrom openai import OpenAI\nclient = OpenAI()\n\nresp = client.responses.create(\n    model=\"gpt-5\",\n    tools=[{\n        \"type\": \"mcp\",\n        \"server_label\": \"fodda\",\n        \"server_description\": \"Expert-curated knowledge graphs for retail, beauty, sports trends and earnings intelligence.\",\n        \"server_url\": \"https://mcp.fodda.ai/mcp\",\n        \"authorization\": \"Bearer YOUR_API_KEY\",\n        \"require_approval\": \"never\",\n    }],\n    input=\"What are the top emerging retail trends?\",\n)\nprint(resp.output_text)\n```\n\n```javascript\nimport OpenAI from \"openai\";\nconst client = new OpenAI();\n\nconst resp = await client.responses.create({\n  model: \"gpt-5\",\n  tools: [{\n    type: \"mcp\",\n    server_label: \"fodda\",\n    server_description: \"Expert-curated knowledge graphs for retail, beauty, sports trends and earnings intelligence.\",\n    server_url: \"https://mcp.fodda.ai/mcp\",\n    authorization: \"Bearer YOUR_API_KEY\",\n    require_approval: \"never\",\n  }],\n  input: \"What are the top emerging retail trends?\",\n});\nconsole.log(resp.output_text);\n```\n\n> **Tip:** To reduce latency with 30+ tools, use `allowed_tools` to filter:\n> `\"allowed_tools\": [\"search_graph\", \"search_statistics\", \"brand_tracker\"]`\n\n> **Legacy:** If you're using `chat.completions.create()` with function calling, define a custom function that calls the Fodda REST API. See [fodda.ai/connect](https://app.fodda.ai) for details.\n\n### Connect from ChatGPT (ChatGPT Apps Directory)\n\nTo connect Fodda to ChatGPT (Apps Directory listing or a custom MCP connection):\n- Server URL: `https://mcp.fodda.ai/chatgpt`\n- Authentication: OAuth 2.1 (PKCE S256, Dynamic Client Registration) — authorization server `https://clerk.fodda.ai` (metadata at `https://clerk.fodda.ai/.well-known/oauth-authorization-server`)\n- Resource metadata discovery: `https://mcp.fodda.ai/.well-known/oauth-protected-resource/chatgpt`\n- Curated tool profile: 24 tools covering trends, brand tracking, earnings intelligence, expert intelligence, and visual generation.\n\n### Generic Streamable HTTP Client\n\nConnect to the `/mcp` endpoint using HTTP `POST` (Streamable HTTP) with `Authorization: Bearer YOUR_API_KEY`:\n```\nhttps://mcp.fodda.ai/mcp\n```\n\n### Gemini / Antigravity\n\nAdd to `~/.gemini/config/mcp_config.json`:\n```json\n{\n  \"mcpServers\": {\n    \"fodda\": {\n      \"serverUrl\": \"https://mcp.fodda.ai/mcp\",\n      \"headers\": {\n        \"Authorization\": \"Bearer YOUR_API_KEY\"\n      }\n    }\n  }\n}\n```\n\n### Generic SSE Client\n\nConnect to `https://mcp.fodda.ai/sse` with an `Authorization: Bearer YOUR_API_KEY` header.\n\n---\n\n## Available Tools\n\nThe Fodda MCP server exposes a rich suite of 30 tools to search, analyze, brainstorm, and visualize trends, expert-curated knowledge graphs, and corporate documents.\n\n### Discovery & Search\n| Tool | Description | Deterministic |\n|------|-------------|:---:|\n| `list_graphs` | Discover available knowledge graphs, metadata, and routing instructions. | ✅ |\n| `search_graph` | Hybrid keyword + semantic search across curated graphs for trend clusters and evidence. | ❌ |\n| `search_statistics` | Search for specific quantitative metrics, indicators, and numeric data points. | ❌ |\n| `search_insights` | Search expert quotes, qualitative signals, and professional interpretations. | ❌ |\n| `get_label_values` | Discover valid values for a node label or category. | ✅ |\n\n### Traversal & Graph Operations\n| Tool | Description | Deterministic |\n|------|-------------|:---:|\n| `get_neighbors` | Traverse from seed nodes to discover related concept nodes and links. | ✅ |\n| `get_node` | Retrieve detailed metadata, properties, and attributes for a single node by ID. | ✅ |\n| `get_evidence` | Retrieve source signals, articles, citations, and provenance for a trend or node. | ✅ |\n| `discover_adjacent_trends` | Find semantically similar trends to a given trend node. | ✅ |\n\n### Intelligence Domains\n| Tool | Description | Deterministic |\n|------|-------------|:---:|\n| `get_domain_intelligence` | Search all PSFK curated domain graphs (retail, beauty, sports, fashion, consumer electronics, F&B) in parallel. | ❌ |\n| `get_expert_intelligence` | Query specialist industry graphs built by leading strategists and experts. | ❌ |\n| `get_report_intelligence` | Search institutional report insights from DHL, PwC, Delta, and other partners. | ❌ |\n\n### Earnings & Corporate Insights\n| Tool | Description | Deterministic |\n|------|-------------|:---:|\n| `get_earnings_intelligence` | Query management commentary, business guidance, and Q&A from company earnings calls. | ❌ |\n| `get_earnings_divergence` | Detect deflections, gaps, and divergence between analyst concerns and executive responses in earnings calls. | ❌ |\n\n### Brand & Ideation\n| Tool | Description | Deterministic |\n|------|-------------|:---:|\n| `brand_tracker` | Compile a comprehensive Brand Intelligence Profile across all knowledge graphs. | ❌ |\n| `brainstorm_topic` | Graph-powered brainstorm map discovering unexpected connections and adjacent territories. | ❌ |\n\n### Deep Research & Execution Agents\n| Tool | Description | Deterministic |\n|------|-------------|:---:|\n| `deep_research_topic` | Launch an autonomous research session combining graphs with live web search. | ❌ |\n| `check_research_status` | Check progress or retrieve the final narrative report of a deep research job. | ✅ |\n| `get_supplemental_context` | Fetch macro context from up to 10 institutional data sources in a single query. | ❌ |\n| `check_supplemental_status` | Retrieve output from a supplemental context job. | ✅ |\n\n### Synthetic Analyst & Visualization\n| Tool | Description | Deterministic |\n|------|-------------|:---:|\n| `list_analysts` | List available Synthetic Analyst expert personas. | ✅ |\n| `consult_analyst` | Engage a Synthetic Analyst persona to synthesize answers with specialized voice. | ❌ |\n| `generate_visual` | Generate branded SVG data visualizations (Cultural Shifts, Competitive Compass, Innovation Pathway, etc.). | ❌ |\n> **Note on Dynamic Partner Skills:** When partner skills (such as Paralogy or Igloo) are enabled for a user's account, additional specialized tools (e.g. `paralogy_analyze_trends`, ideation tools) are dynamically registered on the MCP server and made available automatically.\n>\n> **Note on System Utilities:** The server also registers several helper and account management utilities (e.g., `get_my_account`, `toggle_graph_preference`, `update_user_profile`, `manage_scheduled_reports`, `send_feedback`) to allow the AI assistant to query subscription status, manage scheduled briefings, or save personalization settings directly.\n\n---\n\n### Discovery Endpoints\n\n| Endpoint | Description |\n|----------|-------------|\n| `GET /health` | Health check (`{ \"status\": \"ok\", \"version\": \"...\" }`) |\n| `POST /mcp` | MCP endpoint — call the standard `tools/list` method on an initialized session to retrieve full tool schemas and capabilities |\n\n---\n\n## Authentication\n\n**Preferred — HTTP header (used by the directory connection and all header-capable clients).**\nPass your Fodda API key as a Bearer token:\n\n```\nAuthorization: Bearer sk_live_...\n```\n\nThe server also accepts the key via an `X-API-Key: sk_live_...` header.\n\nIn MCP request `_meta`:\n```json\n{ \"_meta\": { \"authorization\": \"Bearer sk_live_...\" } }\n```\n\n**Fallback — URL query parameter.** Some clients (e.g. the Claude.ai web *custom\nconnector* UI) cannot set custom request headers. For those, the key may be passed as\n`?api_key=...`. This is provided only for compatibility; prefer header-based auth\nwherever the client supports it, since URLs are more likely to be logged by\nintermediaries. The server never returns your API key in tool output.\n\n---\n\n## Configuration\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `PORT` | HTTP server port (omit for stdio mode) | — |\n| `FODDA_API_URL` | Upstream API base URL | `https://api.fodda.ai` |\n| `FODDA_MCP_SECRET` | HMAC signing secret for API requests | — |\n| `NODE_ENV` | Environment (`development` / `production`) | `production` |\n\n---\n\n## Build & Run\n\n```bash\nnpm install\nnpm run build\n\n# Stdio mode\nnpm start\n\n# SSE mode\nPORT=8080 npm start\n```\n\n## Self-Hosting\n\n- **Docker**: `docker build -t fodda-mcp . && docker run -p 8080:8080 -e PORT=8080 fodda-mcp`\n- **Cloud Run**: `./deploy_cloud_run.sh`\n- **Kubernetes**: See [`deployment/k8s/`](./deployment/k8s/)\n- **Terraform**: See [`deployment/terraform/`](./deployment/terraform/)\n\n---\n\n## MCP Registry\n\nThis server is published to the [Official MCP Registry](https://registry.modelcontextprotocol.io) as `ai.fodda/mcp-server`.\n\n```bash\n# Verify listing\ncurl \"https://registry.modelcontextprotocol.io/v0.1/servers?search=ai.fodda/mcp-server\"\n```\n\n---\n\n## Privacy Policy\n\nFull policy: **[https://www.fodda.ai/privacy](https://www.fodda.ai/privacy)**\n\nSummary of how the Fodda MCP server handles data (the hosted policy is authoritative):\n\n- **What we collect.** *Account information* (name, email, organization) to manage your\n  account; *usage data* — API queries (query text, graph accessed, timestamps) logged for\n  billing, service improvement, and abuse prevention; and standard *technical data* (IP,\n  browser type, referral URLs). We do **not** store the full content of AI-generated\n  responses. Your API key authenticates requests and is never returned in tool output.\n- **How it's used.** To provide and improve the Services, process billing, enforce rate\n  limits and prevent abuse, communicate support/service updates, and meet legal\n  obligations. Requests are proxied to the Fodda API (`https://api.fodda.ai`) over TLS.\n- **Third-party sharing.** We do **not** sell your personal information. Data is shared\n  only with service providers (e.g. payment processors, cloud hosting) under\n  confidentiality agreements, or when required by law.\n- **AI model training.** Fodda does **not** use your queries or data to train AI models.\n  Knowledge graphs are expert-curated, not generated from user interactions.\n- **Retention.** Account information is retained while your account is active; query logs\n  are retained for billing and analytics. You may request account/data deletion via the\n  contact below.\n- **Security.** TLS-encrypted connections, API-key authentication, and secure cloud\n  infrastructure.\n- **Contact.** Privacy inquiries: **[privacy@fodda.ai](mailto:privacy@fodda.ai)**.\n\nSee the [full hosted Privacy Policy](https://www.fodda.ai/privacy) (last updated\nJune 16, 2026) for the complete, authoritative terms.\n\n---\n\n## Support\n\n- **Email:** [hello@fodda.ai](mailto:hello@fodda.ai)\n- **Account & API keys:** [app.fodda.ai](https://app.fodda.ai) → Account → MCP Integration\n- **Documentation:** [fodda.ai](https://www.fodda.ai)\n\nTo report a security issue, email **[hello@fodda.ai](mailto:hello@fodda.ai)** with\n\"SECURITY\" in the subject line.\n\n---\n\n## License\n\nProprietary — [fodda.ai](https://www.fodda.ai)\n",
  "bytes": 12853,
  "sha": "63107b257cafb953b99c45220958f01f0c4f0cd7233b1a84ad5955d6a0117227",
  "repo_slug": "piers-fawkes/fodda-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_ai_fodda_topic_research_4c302869/readme"
}