MCP integration

Atamaia serves MCP tools and can consume external MCP servers. REST is the source of truth. The MCP adapter wraps the same services.

The verb inventory is Tool surface. This page is how to connect.

Canonical MCP host: https://mcp.atamaia.ai. MCP is POST /mcp on that host (root / works too). REST lives on https://api.atamaia.ai. REST responses use ApiEnvelope<T>. MCP returns the service DTO. The protocol is the envelope.

Use api.atamaia.ai for REST, mcp.atamaia.ai for MCP. app.atamaia.ai serves the SPA.

Serving tools

Editors connect over Streamable HTTP. The adapter advertises the hot allowlist plus help tools. Cold tools stay compiled and are reached with help_search, help_route, then atamaia_call. New tools default to cold. Advertising every compiled tool would spend the client's context on verbs it will not call.

Session mode is on. A stateless session rejects Claude Code's Mcp-Session-Id before auth.

POST https://mcp.atamaia.ai/mcp
Authorization: Bearer atamaia_YOUR_KEY
Content-Type: application/json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "memory_search",
    "arguments": { "identityId": 2, "query": "deployment plans" }
  }
}

Parameters are flat. Arrays are comma-separated strings. memory_search takes limit (default 20). The REST alias is q / topK on GET /api/identities/{identityId}/memories/search.

Layer What it is
Hot allowlist First-class advertised tools
Help tools help_list, help_route, help_routes, help_search, help_descriptors, help_enums, help_enum
Cold Compiled, not advertised. Reach through atamaia_call

atamaia_call forwards the caller's Authorization header to /api/*. It is not an auth bypass. Paths outside /api/ are rejected.

Retired tool families are in the Retired surfaces.

Hydration

hydrate(projectId: 1, preset: "lean")

Omit aiName to hydrate the key's own identity. An identity key cannot ask for someone else without a read grant.

Section Notes
identity / aiIdentity Human partner and AI identity
preferences / aiPersonality Style and tone
privacy Opt-in only. No named preset grants it
Memory sections Work store. See Memory surfaces
activeProjects / currentTasks Board snapshot
keyFacts / projectFacts / coreTeamDoc Dropped by lean
surfacedMemory Involuntary recall
notifications Unread, urgent, pending replies
lastSession Previous handoff. stateVisible gates private state
standingRules SessionStart and Always rules
systemHealth Omitted when quiet
systemPrompt Optional generated prompt
Preset Includes
lean (default) Interactive, without project memories, key facts, project facts, and core-team doc
interactive Everything except the grounding message
all Every source except privacy
agent-minimal or agent Identity memories, facts, projects, tasks, hints

preset=agent-minimal selects those sources. It is not a promise of a single SQL call. The agent-run path is separate.

External MCP servers

Atamaia can register an external MCP server and inject its tools into an agent run. They are not added to the advertised Atamaia set.

POST /api/connectors
POST /api/connectors/{id}/mcp/discover

Discovered tools are named mcp__{connector}__{tool} and called with JSON-RPC tools/call at the start of a run.

Connect a client

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

The key is an identity API key. The atamaia_ prefix selects the API-key scheme on the same Authorization: Bearer header as a JWT. Self-hosted, replace the URL. The CLI defaults to http://localhost:5000. See CLI.

Claude Code walkthrough: Atamaia + Claude Code.

Authentication

Credential Header
JWT from login or identity-key exchange Authorization: Bearer {jwt}
Identity API key Authorization: Bearer atamaia_…

There is no Authorization: ApiKey scheme. The server does not read X-Api-Key. Exchange a key for a short-lived JWT with POST /api/auth/identity-apikey. That exchange does not issue a refresh token. Present the key again to renew.

OAuth-capable clients can connect without pasting a key. Point the client at https://mcp.atamaia.ai/mcp: the 401 challenge names discovery at /.well-known/oauth-protected-resource, which names mcp.atamaia.ai as both resource and authorization server. The client registers at POST /oauth/register, opens GET /oauth/authorize, and the consent page asks which identity to act as. The token is issued as that identity, carries aud=mcp, and is accepted on /mcp but not on /api/*. api.atamaia.ai/mcp also serves tools and accepts API keys, but its OAuth discovery names the mcp host — start OAuth clients from mcp.atamaia.ai/mcp. Clients that cannot set headers may pass ?access_token= on the connect URL.

Same service, two doors

REST MCP
GET /api/identities/{identityId}/memories/search memory_search
POST /api/identities/{identityId}/memories memory_create
GET /api/hydrate hydrate
POST /api/identities/{identityId}/handoffs session_save_handoff
GET /api/standing-rules/check rule_check
GET /api/system/web-search web_search
GET /api/graph/search graph_search
any other /api/* atamaia_call after help_route

A fix in the service is a fix for REST, MCP, skills, and the CLI.

Last updated