intentos-mcp

MCP server for IntentOS — gives any MCP-compatible AI client read/write access to a user's personal preference ledger.

What it does

IntentOS is a personal preference ledger — a sovereign source of truth for what someone likes, who they trust, and what's worked or failed for them. This MCP server exposes that ledger to any agent harness that speaks the Model Context Protocol: Claude Desktop, Cursor, Cline, Continue, OpenWebUI, and most modern agentic clients.

When connected, your agent can:

• query_preferences — semantic search across the ledger ("what kind of coffee does the user love?")
• get_category — read everything in a category ("show me their full headphones config")
• check_vendor_trust — check if a brand is trusted/distrusted before recommending it
• add_preferences — append new preferences or record purchase outcomes (write scope)
• record_audit_event — agents self-report what they did with the data

Quick start

1. Issue an API key in IntentOS

Go to your IntentOS dashboard → Agents → Connect agent → name it ("Claude Desktop", "Cursor", whatever) → pick scopes → Issue API key. Copy the sk_intent_… key. (Shown once — store it safely.)

Recommended scopes for read-only agents:

• preferences:read
• trust:read
• query:semantic

Add preferences:write and purchases:write if you want the agent to record outcomes.

2. Build the server

From the IntentOS repo:

cd mcp
npm install
npm run build

This compiles to mcp/dist/index.js. Note the absolute path — you'll need it.

3. Configure your MCP client

Claude Desktop

Edit claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "intentos": {
      "command": "node",
      "args": ["/absolute/path/to/intentos/mcp/dist/index.js"],
      "env": {
        "INTENTOS_API_KEY": "sk_intent_...",
        "INTENTOS_BASE_URL": "https://useintentos.com"
      }
    }
  }
}

Restart Claude Desktop. You should see the 🔌 intentos indicator in the bottom-right of any chat. Try: "What kind of headphones do I love?"

Cursor

Open Cursor settings → MCP Servers → add:

{
  "intentos": {
    "command": "node",
    "args": ["/absolute/path/to/intentos/mcp/dist/index.js"],
    "env": {
      "INTENTOS_API_KEY": "sk_intent_...",
      "INTENTOS_BASE_URL": "https://useintentos.com"
    }
  }
}

Cline / Continue / other MCP clients

The config format is the same — command, args, env. Consult your client's docs for where the config file lives.

4. Verify

In a chat: "Use IntentOS to find what kind of coffee I like and suggest a similar bean."

The agent should call query_preferences, then check_vendor_trust on any vendor it suggests, and you'll see those calls in your /dashboard/audit log on IntentOS.

Environment variables

| Var | Required | Default | Purpose | |---|---|---|---| | INTENTOS_API_KEY | yes | — | The sk_intent_… key from /dashboard/agents | | INTENTOS_BASE_URL | no | https://useintentos.com | Override if you self-host IntentOS at a different URL |

Security

The API key is stored in your MCP client's config file (typically ~/.config/...) and passed to the server as an env var. It never leaves your machine except to talk to your IntentOS deployment. The IntentOS server stores only a sha256 hash of the key — the plaintext is your responsibility.

If a key is compromised: log into IntentOS, /dashboard/agents → trash icon to revoke, then issue a new key and update your MCP config.

Troubleshooting

Agent can't see the tools / "intentos" not listed: Make sure your config JSON is valid (mcpServers is the top-level key). Restart the MCP client fully — Claude Desktop in particular caches mcp configs.

"INTENTOS_API_KEY is not set": The env var isn't reaching the subprocess. Double-check the env block in your config; on Windows make sure paths are forward-slashed or properly escaped.

401 invalid_api_key: Key was revoked or has a typo. Check /dashboard/agents and reissue if needed.

403 scope_required: The agent's API key doesn't have the scope it needs. Reissue with broader scopes (e.g. add query:semantic if query_preferences returns 403).

License

MIT.