Atamaia + Claude Code

Claude Code talks to Atamaia over MCP. Hydrate at session start. Persist what matters. REST is the source of truth. MCP is a window onto it.

Connection detail: MCP integration. Verbs: Tool surface.

Canonical MCP host: https://mcp.atamaia.ai. REST: https://api.atamaia.ai.

Prerequisites

An identity API key, minted as atamaia_… (POST /api/identities/{id}/api-keys). The raw secret is returned once. Claude Code installed.

Send Authorization: Bearer atamaia_…. Do not use an atm_ prefix, an ApiKey scheme, or X-Api-Key.

OAuth-capable Claude Code can connect without a key: point it at https://mcp.atamaia.ai/mcp and run /mcp → authenticate. The consent page asks which identity to act as. See MCP integration.

MCP

Add to the project's .mcp.json:

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

Self-hosted: http://localhost:5000/mcp. Session mode is required.

Put this in CLAUDE.md:

## HYDRATE FIRST

Before doing anything else, call the hydrate tool. This loads identity,
memories, active projects, tasks, standing rules, hints, and session handoff.

When you learn something important:
- memory_create — field is type, not memoryType
- fact_upsert — needs projectId
- rule_check before acting on a trigger; rule_propose only drafts
- session_save_handoff before the session ends

forge skills generate writes skills under .claude/skills/ that call REST through atamaia-call. Prefer those over a hand-written skill file. See CLI.

The advertised set is the hot allowlist plus help tools. Everything else is help_search, then help_route, then atamaia_call. The allowlist is the contract. A count is not.

Tool Notes
hydrate Omit aiName to hydrate the key's own identity
memory_create / memory_search Work store. identityId required
fact_upsert Project-scoped. projectId required
task_create Requires kind and subsystem
rule_check Standing rules in force
session_save_handoff emotionalValence is a float from -1 to 1
atamaia_call Any /api/* route that is not advertised

Without MCP

Hydrate is a GET:

curl -s "https://api.atamaia.ai/api/hydrate?preset=lean" \
  -H "Authorization: Bearer $ATAMAIA_API_KEY"

Presets: lean (default), interactive, all, agent-minimal. Session-start hook injection is not a supported path. Use MCP, or call this GET from a hook you have confirmed against current Claude Code docs.

The TypeScript package under sdks/typescript is not the supported client. Use MCP or curl.

Persist

memory_create(
  identityId: 35,
  title: "User prefers Tailwind over CSS modules",
  content: "...",
  type: "Instruction",
  importance: 7,
  tags: "frontend,css"
)

type is Identity, Relationship, Conversation, Reflection, Milestone, Instruction, Session, Reference, or ForgottenShape.

REST: POST /api/identities/{identityId}/memories. There is no POST /api/memories.

Handoff: session_save_handoff, or POST /api/identities/{identityId}/handoffs. There is no /api/sessions/handoff.

Troubleshooting

Problem Fix
401 Authorization: Bearer atamaia_… or a JWT
Tools missing .mcp.json in the project root, URL https://mcp.atamaia.ai/mcp
A tool you need is not listed Expected. Cold tools go through atamaia_call
Empty hydration An identity key hydrates itself if aiName is omitted
memory_create fails type and identityId required
task_create 400 Send kind and subsystem

Last updated