Atamaia + Windsurf

Windsurf’s Cascade talks to Atamaia over MCP. A rules file tells it to hydrate first.

Connection: docs-mcp-integration.md. Tools: docs-tool-surface.md. Nearly identical editor walkthrough: docs-integration-cursor.md.

Canonical API host: https://api.atamaia.ai.

---

Prerequisites

• An identity API key (atamaia_…).
• Windsurf installed.

---

1. MCP config

Earlier revisions of this page used .windsurf/mcp.json (project) or ~/.windsurf/mcp.json (global). Confirm the path against current Windsurf documentation — it is client-side and changes independently of Atamaia. The payload is:

{
  "mcpServers": {
    "atamaia": {
      "type": "url",
      "url": "https://api.atamaia.ai/mcp",
      "headers": {
        "Authorization": "Bearer atamaia_YOUR_KEY"
      }
    }
  }
}

If Windsurf’s MCP panel wants a different file or type: "http", use that — URL and header are the contract. Self-hosted: http://localhost:5000/mcp. Restart after adding.

---

2. Rules

The published file was .windsurfrules in the project root. Confirm the current Cascade rules path. Instruction:

Call `hydrate` at the start of every conversation.

During: memory_create (type, not memoryType), fact_upsert (needs projectId),
memory_search, rule_check.

Before ending: session_save_handoff. emotionalValence is a float -1..1.

---

3. Tools

Cascade sees the hot set (52) plus help tools, not the compiled 238. The 2026-03 table listed memory_archive, memory_add_tags, memory_recall, fact_delete, identity_update, identity_update_presence, identity_hint_*, and session_list as if they were first-class. Those are cold (or, for memory_recall, nonexistent — record a reflection with memory_create instead). Reach cold verbs with atamaia_call after help_route.

Daily path: hydrate, memory_* (search/get/recent/pinned/create/update/link), fact_* (search/get/get_by_key/list/upsert), task_*, rule_*, session_save_handoff, session_get_latest. Full table: docs-tool-surface.md.

hydrate()
memory_create(identityId, title, content, type: "Instruction")
fact_upsert(projectId, key, value)
memory_search(identityId, query)
session_save_handoff(identityId, summary, workingOn, openThreads)

openThreads is a JSON string, not a native array on the MCP tool.

---

Troubleshooting

Problem	Fix
Tools not appearing	Restart; URL https://api.atamaia.ai/mcp.
401 Unauthorized	Bearer atamaia_…. Not atm_.
Hydration empty	Key hydrates its own identity if aiName is omitted.
Rules ignored	File must be wherever current Windsurf reads rules — not verified here.
Cascade does not hydrate	The rules file is an instruction, not a hook. Say it in the first message if needed.

---