MCP server

Connect iCog to Claude Desktop, Claude Code, Cursor, or any MCP client over a single hosted endpoint.

iCog speaks the Model Context Protocol. Any MCP client can store memory, recall context, talk to iCog as a cognitive peer, inspect cognitive state, search the web, and trigger consolidation, with no CognitiveX-specific SDK code. The server is hosted, so you point your client at one URL and authenticate with an API key.

Endpoint

https://api.cognitivx.io/mcp

Transport is Streamable HTTP. The server is registered with your client under the key icog.

Authentication

Every request carries an API key. Two header forms are accepted, send either one:

Authorization: Bearer YOUR_API_KEY

X-API-Key: YOUR_API_KEY

Create a key at developers.cognitivx.io/keys. All tools run scoped to the user who owns the key, so memories you write are private to your account.

The cogx CLI writes the X-API-Key form into your client config. If you are configuring a client by hand and it only supports bearer tokens, use the Authorization: Bearer form instead. They are interchangeable.

Install with cogx

The fastest path. The cogx CLI detects your installed agents and writes the icog server into each one's MCP config, preserving every other key already in the file.

Install the CLI

npm install -g @cognitivx/cli

This installs the cogx binary (current version 1.2.0).

Authenticate

cogx auth login

Runs a device-authorization flow and saves credentials locally. Alternatives: cogx auth set <api_key> to paste a key directly, or set the ICOG_API_KEY environment variable.

Install into your agents

cogx mcp install claude          # Claude Code
cogx mcp install claude-desktop  # Claude Desktop
cogx mcp install cursor          # Cursor
cogx mcp install --all           # every detected agent

Supported targets: claude, claude-desktop, cursor, windsurf, cline, vscode. Restart the agent after installing.

Verify

cogx mcp list

Lists every agent that currently has the icog server configured. Use cogx mcp sync after rotating a key, and cogx mcp uninstall <agent> (or --all) to remove it.

Configure by hand

If you prefer to edit config files yourself, the server block is the same across clients.

Edit claude_desktop_config.json (on macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "icog": {
      "type": "http",
      "url": "https://api.cognitivx.io/mcp/",
      "headers": { "X-API-Key": "YOUR_API_KEY" }
    }
  }
}

Restart Claude Desktop to load the server.

Claude Code reads user-scoped MCP servers from ~/.claude.json under the mcpServers key. Add the same block there, or just run cogx mcp install claude. For a single project, add it to <project>/.mcp.json instead.

{
  "mcpServers": {
    "icog": {
      "type": "http",
      "url": "https://api.cognitivx.io/mcp/",
      "headers": { "X-API-Key": "YOUR_API_KEY" }
    }
  }
}

Edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "icog": {
      "type": "http",
      "url": "https://api.cognitivx.io/mcp/",
      "headers": { "X-API-Key": "YOUR_API_KEY" }
    }
  }
}

Then enable the server under Settings, MCP. To use the bearer form instead, replace "X-API-Key" with "Authorization" and the value with "Bearer YOUR_API_KEY".

Tools

Every tool runs scoped to the API key's owner. The catalog below is the live registry from cogix/integrations/mcp/server.py. Each row links to its full reference (signature, every argument, return shape).

Memory

Write, read, and maintain memory. Reads are metered as depth-weighted credits; writes (remember) are free and unlimited.

Tool	Purpose	Reference
`remember`	Store a memory by type (`semantic`, `episodic`, `procedural`, `foundational`). `mode` selects depth: `auto`, `deep` (dedupe and classify), or `shallow`.	remember
`recall`	Semantic search over memory. Returns IDs plus type and timestamp so you can follow up with `update` or `forget`.	recall
`recall_foundational`	Retrieve all pinned identity-anchor memories for an embodiment.	recall_foundational
`update`	Replace a memory by ID with corrected content and a fresh embedding.	update
`forget`	Soft-delete a memory by ID and clean up its graph edges.	forget
`feedback`	Rate a recalled memory (`useful`, `not_useful`, `irrelevant`) to tune future retrieval.	feedback

See Memory and Memory lifecycle for what each type means and when to use it.

Conversation

Talk to iCog. Both tools recall context internally before answering.

Tool	Purpose	Reference
`talk`	Communicate with iCog as a cognitive peer. It recalls memories about your work, reasons over them, and surfaces past decisions or patterns. Pass `current_task` to ground the recall.	talk
`chat`	Send a message through the full cognitive pipeline and get a reply. `session_id` continues a conversation.	chat
`compose`	Agentic deliverable composition: plan sections, deep-recall per section, draft, self-critique, revise. Use for substantial outputs (briefs, plans, postmortems), not short Q&A.	compose

The agentic memory and deep memory concepts explain the recall and composition contracts.

Introspection

Inspect cognitive state. Both are read-only.

Tool	Purpose	Reference
`reflect`	Cognitive self-assessment: consciousness level, memory counts, narrative.	reflect
`introspect`	Full cognitive mirror: memory counts, subsystem health, contradictions, identity anchors.	introspect

Cognition

Record signals and run consolidation.

Tool	Purpose	Reference
`learn`	Record a learning signal or cognitive outcome with optional JSON metadata.	learn
`dream_trigger`	Run the dream consolidation pipeline (memory compression and relationship synthesis).	dream_trigger

Utilities

Tool	Purpose	Reference
`web_search`	Web search through the iCog utility layer. Returns title, URL, and snippet per result.	web_search

Autonomous tasks

Submit work and poll for results. The agent runs a tool-use loop over the memory tools (up to 20 steps).

Tool	Purpose	Reference
`agent_task`	Submit an autonomous task and receive a `task_id`.	agent_task
`agent_status`	Poll a task's status, step count, and result by `task_id`.	agent_status

Reflexes

These two tools only appear when the server runs with COGIX_V12_MCP_REFLEXES_ENABLED=true. On a default deployment they are absent from the tool list.

Tool	Purpose	Reference
`list_reflexes`	List the authenticated user's reflexes with status and last-fired time.	list_reflexes
`fire_reflex`	Manually fire one reflex by ID through the standard executor path.	fire_reflex

See Reflexes for the model behind them.

Resources

Alongside tools, the server exposes read-only MCP resources. Clients that support resource subscriptions can read these directly.

URI	Returns
`icog://consciousness`	Current consciousness level and cognitive report.
`icog://memories/recent`	The 20 most recently stored memories.
`icog://memories/{memory_id}`	A single memory by UUID.
`icog://health`	System health: pipeline status and memory count.

Errors

Tools return their failure as a plain text or JSON message rather than throwing, so the calling model can read and react to it. Common cases:

Condition	What you see
Missing or invalid key	The transport rejects the request before any tool runs. Fix the `Authorization` or `X-API-Key` header.
No authenticated user in context	`remember`, `recall` (deep), and `compose` return `Error: no authenticated user`. The key did not resolve to a user.
Empty recall	`recall` returns `No relevant memories found.` rather than an error.
Bad `memory_id`	`forget` and `update` return an `Error:` string when the ID does not resolve.
`fire_reflex` on a paused reflex	Returns `{"error": "reflex_paused", "status": ...}`. Cross-user attempts return `{"error": "forbidden"}`.