Atamaia + VS Code

Several ways in. The contract is the same on every path: Streamable HTTP MCP at /mcp, or REST at https://api.atamaia.ai. Auth is Authorization: Bearer atamaia_… (or a JWT).

MCP adapter: docs-mcp-integration.md. Tools: docs-tool-surface.md. REST/SDK: docs-sdk-api-guide.md.

	Hosted	Self-hosted
REST	https://api.atamaia.ai	http://localhost:5000
MCP	https://api.atamaia.ai/mcp	http://localhost:5000/mcp
Transport	Streamable HTTP	Streamable HTTP
Auth	Authorization: Bearer atamaia_…	Same

aim.atamaia.ai is the SPA. Do not use it as the API or OpenAPI base.

---

1. GitHub Copilot + MCP (recommended)

1.1 .vscode/mcp.json

VS Code’s config key is servers, not mcpServers. Type for a remote server is http. Official reference: MCP configuration (page dated 2026-08-12).

{
  "servers": {
    "atamaia": {
      "type": "http",
      "url": "https://api.atamaia.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${input:atamaia-api-key}"
      }
    }
  },
  "inputs": [
    {
      "id": "atamaia-api-key",
      "type": "promptString",
      "description": "Atamaia API Key",
      "password": true
    }
  ]
}

Local: swap the URL to http://localhost:5000/mcp.

The Agent Host also reads a workspace .mcp.json (Claude Code’s shape). Prefer one file and do not commit keys. ${input:…} values are stored by VS Code; they are not forwarded to the Agent Host the same way a static header is.

1.2 Instructions

A workspace instruction file that tells Copilot to hydrate first is still the right idea. The 2026-03 page used .github/copilot-instructions.md. Confirm that path against current Copilot docs before treating it as a contract. The text:

This project uses Atamaia for identity and memory.

At the start of every conversation, call the `hydrate` tool.
Do not skip it.

Persist decisions with `memory_create` (`type`, not `memoryType`).
Look up prior context with `memory_search` before answering from scratch.
Structured data: `fact_upsert` (needs `projectId`).
Tasks: `task_create` requires `kind` and `subsystem`.

1.3 Tools

Hot set only, plus help. See docs-tool-surface.md. There is no memory_recall tool — reflect into the work store with memory_create (type Reflection). There is no cognitiveState on hydrate.

---

2. Continue / Cline

Both speak MCP. Point them at the same URL and header:

URL:       https://api.atamaia.ai/mcp
Transport: Streamable HTTP (HTTP, with SSE fallback on some clients)
Auth:      Authorization: Bearer atamaia_YOUR_KEY

Exact Continue (~/.continue/config.json) and Cline (saoudrizwan.claude-dev settings) JSON was not re-verified against those products. Do not copy the 2026-03 transport / transportType / customCommands blocks as if they were Atamaia contracts. If the client’s MCP panel accepts a URL + header, that is enough.

Auto-hydration is an instruction you write in that client, not an Atamaia feature.

---

3. VS Code tasks + REST

Hydrate is GET. Memory routes are identity-scoped.

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Atamaia: Hydrate",
      "type": "shell",
      "command": "curl",
      "args": [
        "-s",
        "-H", "Authorization: Bearer ${input:atamaiaApiKey}",
        "https://api.atamaia.ai/api/hydrate?preset=lean"
      ],
      "presentation": { "reveal": "always", "panel": "dedicated", "clear": true },
      "problemMatcher": []
    },
    {
      "label": "Atamaia: Search Memories",
      "type": "shell",
      "command": "curl",
      "args": [
        "-s",
        "-H", "Authorization: Bearer ${input:atamaiaApiKey}",
        "https://api.atamaia.ai/api/identities/${input:identityId}/memories/search?q=${input:searchQuery}"
      ],
      "problemMatcher": []
    }
  ],
  "inputs": [
    { "id": "atamaiaApiKey", "type": "promptString", "description": "Atamaia API Key", "password": true },
    { "id": "identityId", "type": "promptString", "description": "Identity ID" },
    { "id": "searchQuery", "type": "promptString", "description": "Memory search query" }
  ]
}

There is no POST /api/memory. Create is POST /api/identities/{identityId}/memories with title, content, type, optional provenance / importance / tags. See docs-memory-surfaces.md.

Do not run npx @atamaia/sdk hydrate as a task. The shipped SDK is stale (docs-sdk-api-guide.md).

---

4. Extension authors

Talk to REST. Do not depend on @atamaia/sdk until it sends Authorization: Bearer to https://api.atamaia.ai.

const base = "https://api.atamaia.ai";
const headers = {
  Authorization: `Bearer ${apiKey}`,
  Accept: "application/json",
};

const hydrate = await fetch(`${base}/api/hydrate?preset=lean`, { headers });
const envelope = await hydrate.json(); // ApiEnvelope<HydrationContext>

Envelope shape: docs-sdk-api-guide.md. Hydration sections: docs-mcp-integration.md. There is no cognitiveState field to render.

---

Other clients

Claude Code: docs-integration-claude-code.md. Cursor: docs-integration-cursor.md. Windsurf: docs-integration-windsurf.md. OpenAI-compatible HTTP: docs-integration-openai.md (/v1/chat/completions, /v1/responses).

---

Troubleshooting

Problem	Fix
MCP server not in Copilot	.vscode/mcp.json with "servers" (not mcpServers); type: "http"; reload window; Output → MCP.
401 Unauthorized	Bearer atamaia_…. Space after Bearer. Not atm_.
Connection refused (local)	curl http://localhost:5000/health. Use http://, not https://.
Hydration empty	Key is bound to an identity. GET /api/identities / identity_list — there is no GET /api/identity.
Search task 404	Path is /api/identities/{id}/memories/search, not /api/memory/search.

---