README.md
Expert-curated knowledge graphs for AI agents
Fodda MCP Server
Expert-curated knowledge graphs for AI agents — PSFK Retail, Beauty, Sports and partner datasets via the Model Context Protocol.
Quick Start
Claude Code (Streamable HTTP fallback to SSE)
claude mcp add --transport sse fodda https://mcp.fodda.ai/sse \
--header "Authorization: Bearer YOUR_API_KEY"
OpenAI Frontier or Streamable HTTP Client
Connect to the /mcp endpoint using HTTP GET to establish a stream and POST to execute:
https://mcp.fodda.ai/mcp
Gemini CLI
{
"tools": [{
"type": "mcp",
"name": "fodda",
"url": "https://mcp.fodda.ai/sse",
"headers": { "Authorization": "Bearer YOUR_API_KEY" }
}]
}
Generic SSE Client
Connect to https://mcp.fodda.ai/sse with an Authorization: Bearer YOUR_API_KEY header.
Available Tools
| Tool | Description | Deterministic |
|---|---|---|
search_graph |
Hybrid keyword + semantic search on a knowledge graph | ❌ |
get_neighbors |
Traverse from seed nodes to discover related concepts | ✅ |
get_evidence |
Source signals, articles, and provenance for a node | ✅ |
get_node |
Retrieve metadata for a single node by ID | ✅ |
get_label_values |
Discover valid values for a node label/category | ✅ |
psfk_overview |
Structured macro overview across industries and sectors | ❌ |
All tools require userId and — except psfk_overview — a graphId.
Discovery Endpoints
| Endpoint | Description |
|---|---|
GET /mcp/tools |
Full tool schemas, versions, and capabilities |
GET /health |
Health check ({ "status": "ok" }) |
GET /.well-known/mcp.json |
MCP server auto-discovery manifest |
Authentication
Pass your Fodda API key as a Bearer token:
Authorization: Bearer fk_live_...
In MCP request _meta:
{ "_meta": { "authorization": "Bearer fk_live_..." } }
Configuration
| Variable | Description | Default |
|---|---|---|
PORT |
HTTP server port (omit for stdio mode) | — |
FODDA_API_URL |
Upstream API base URL | https://api.fodda.ai |
FODDA_MCP_SECRET |
HMAC signing secret | — |
ALLOWED_TOOLS |
Comma-separated allowlist of Enterprise Tool scope | search_graph,get_node,... |
NODE_ENV |
Environment (development / production) |
production |
INTERNAL_TEST_KEYS |
Comma-separated keys for simulation mode | — |
RATE_LIMIT_RPM |
Requests per minute per API key | 60 |
Build & Run
npm install
npm run build
# Stdio mode
npm start
# SSE mode
PORT=8080 npm start
Self-Hosting
- Docker:
docker build -t fodda-mcp . && docker run -p 8080:8080 -e PORT=8080 fodda-mcp - Cloud Run:
./deploy_cloud_run.sh - Kubernetes: See `deployment/k8s/`
- Terraform: See `deployment/terraform/`
MCP Registry
This server is published to the Official MCP Registry as io.github.piers-fawkes/fodda.
# Verify listing
curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.piers-fawkes/fodda"
License
Proprietary — fodda.ai
Tools (6)
search_graphHybrid keyword and semantic search on a knowledge graphget_neighborsTraverse from seed nodes to discover related conceptsget_evidenceSource signals, articles, and provenance for a nodeget_nodeRetrieve metadata for a single node by IDget_label_valuesDiscover valid values for a node label or categorypsfk_overviewStructured macro overview across industries and sectorsEnvironment Variables
PORTHTTP server portFODDA_API_URLUpstream API base URLFODDA_MCP_SECRETHMAC signing secretALLOWED_TOOLSComma-separated allowlist of Enterprise Tool scopeNODE_ENVEnvironment (development / production)INTERNAL_TEST_KEYSComma-separated keys for simulation modeRATE_LIMIT_RPMRequests per minute per API keyConfiguration
claude_desktop_config.json
{"mcpServers": {"fodda": {"command": "npx", "args": ["-y", "fodda-mcp"], "env": {"FODDA_API_KEY": "YOUR_API_KEY"}}}}Try it
→Search the knowledge graph for recent trends in sustainable beauty packaging.
→Get the neighbors for the 'Gen Z Retail' node to understand related consumer behaviors.
→Provide a macro overview of the current sports technology sector using psfk_overview.
→Retrieve the evidence and source articles for the node with ID 'retail-innovation-001'.
→List all valid values for the 'industry' label in the retail graph.