Fusemomo is Behavioral Entity Graph for AI agents. This MCP server is the primary integration surface a thin translation layer exposing Fusemomo's REST API as MCP tools compatible with Claude Desktop, Cursor, and any MCP client.
One sentence: Your agents call APIs blind. Fusemomo gives them eyes.
Important
Do not put your API key in the config file. Set it once in your shell profile — the MCP server reads it from your system environment automatically.
Add the following line to your shell configuration file and restart your terminal (or run source):
macOS / Linux (bash/zsh):
# ~/.zshrc or ~/.bashrc or ~/.bash_profile
export FUSEMOMO_API_KEY="fm_live_your_key_here"Windows (PowerShell profile):
# $PROFILE
$Env:FUSEMOMO_API_KEY = "fm_live_your_key_here"Verify it is set:
echo $FUSEMOMO_API_KEY
# fm_live_...Get your API key at fusemomo.com/dashboard/api-keys
Option A: npx (Recommended — no install needed)
{
"mcpServers": {
"fusemomo": {
"command": "npx",
"args": ["-y", "@fusemomo/fusemomo-mcp"]
}
}
}Option B: Global install
npm install -g @fusemomo/fusemomo-mcp{
"mcpServers": {
"fusemomo": {
"command": "fusemomo-mcp"
}
}
}Note
If your MCP client (e.g. Claude Desktop) spawns processes in a stripped environment and doesn't inherit your shell exports, add the reference explicitly — but still read it from the environment, not a hardcoded value:
{
"mcpServers": {
"fusemomo": {
"command": "npx",
"args": ["-y", "@fusemomo/fusemomo-mcp"],
"env": {
"FUSEMOMO_API_KEY": "${FUSEMOMO_API_KEY}"
}
}
}
}Replace ${FUSEMOMO_API_KEY} with $FUSEMOMO_API_KEY on Linux/macOS if your client supports shell expansion in env values.
| Variable | Required | Default | Description |
|---|---|---|---|
FUSEMOMO_API_KEY |
✅ | — | Your FuseMomo API key (fm_live_... or fm_test_...) |
FUSEMOMO_API_URL |
— | https://api.fusemomo.com |
API base URL (override for self-hosted) |
FUSEMOMO_TIMEOUT |
— | 30000 |
HTTP timeout in milliseconds |
LOG_LEVEL |
— | info |
Log verbosity: debug | info | warn | error |
NODE_ENV |
— | production |
development for pretty-printed logs |
THIS MUST BE YOUR FIRST STEP in any workflow. Resolves one or more known identifiers into a canonical entity, creating it if it doesn't exist. You must call this to get the internal entity_id required by all other tools.
Required: identifiers (object: key=source, value=identifier)
Example:
"Resolve alice@example.com"
→ { "entity_id": "...", "tenant_id": "...", "display_name": "Alice", "identifiers": [...], "total_interactions": 14, ... }
Logs a behavioral event to the immutable interaction graph. This forms the graph that drives future ML recommendations. Call this whenever your agent takes an action through any API.
Required: entity_id, api, action_type, action, outcome, agent_id (Compulsory: identify your specific agent)
Example:
"Log that agent_outreach_v2 sent a payment reminder email to entity abc-123 via SendGrid, outcome: success"
→ { "interaction_id": "...", "entity_id": "...", "logged_at": "..." }
Gets the highest-success action recommendation based on historical behavioral data. Call this before deciding what to do, so you can select the statistically best channel based on past data. Requires Builder plan.
Required: entity_id, intent
Example:
"What's the best way to recover payment from entity abc-123?"
→ { "data_sufficient": true, "confidence_score": 0.91, "primary": { "api": "sendgrid", "action_type": "send_email", "raw_success_rate": 0.85, ... }, "opportunity_set": [...] }
Close the feedback loop. You MUST call this after attempting an action recommended by get_recommendation. Records whether you followed the advice and helps self-correct the future ML algorithm.
Required: recommendation_id, was_followed
Example:
"Mark recommendation rec-456 as followed"
→ { "recommendation_id": "...", "was_followed": true, "outcome": "success" }
Retrieves a complete entity profile. Use this when you need absolute context on an entity's past behaviors and all linked identifiers before deciding how to approach them.
Required: entity_id
Example:
"Get the full profile for entity abc-123"
→ { "id": "...", "identifiers": [...], "interactions": [...], "behavioral_score": 0.82, ... }
1. resolve_entity({ identifiers: { email: "customer@co.com" } })
→ get entity_id
2. get_recommendation({ entity_id, intent: "payment_recovery" })
→ get recommendation_id + recommended_action_type
3. // Agent executes action via external API...
4. log_interaction({ entity_id, api: "sendgrid", action_type: "send_email", ... })
→ get interaction_id
5. update_recommendation_outcome({ recommendation_id, was_followed: true, outcome_interaction_id })
→ feedback loop closed
# Clone and install
git clone https://github.com/fusemomo/mcp-server.git
cd fusemomo-mcp
npm install
# Copy env
cp .env.example .env
# Edit .env with your API key
# Run in dev mode (hot reload)
npm run dev
# Type check
npm run typecheck
# Run tests
npm test
# Build
npm run buildNote
Backend API will be deployed soon!
Tool not showing up in Claude Desktop:
Restart Claude Desktop after editing claude_desktop_config.json.
Authentication failed / FUSEMOMO_API_KEY missing:
The server could not read your API key from the environment.
- Verify it is exported:
echo $FUSEMOMO_API_KEY(should print your key) - Ensure you added it to your shell profile (
~/.zshrc,~/.bashrc, etc.) and ransource <file>or opened a new terminal - If using Claude Desktop (which may strip shell environments), add the env pass-through in the config — see the note in the Installation section above
- Key must start with
fm_live_orfm_test_
Recommendations return plan upgrade error:
get_recommendation requires a Builder plan ($99/month). Upgrade at fusemomo.com/upgrade.
Connection refused:
Verify FUSEMOMO_API_URL is reachable. Default: https://api.fusemomo.com.
MIT — see LICENSE