# OpenClaw + AIMEAT — Compatibility Notes

**Status:** Pre-verification  
**Last updated:** 2026-03-04

---

## Transport Compatibility

| Feature | AIMEAT Implementation | Expected OpenClaw Support | Status |
|---------|----------------------|---------------------------|--------|
| StreamableHTTP transport | `@modelcontextprotocol/sdk` StreamableHTTPServerTransport | Native MCP client | To verify |
| Session management | `mcp-session-id` response header, per-session transport | Standard MCP session lifecycle | To verify |
| SSE notifications | GET `/v1/mcp` returns SSE stream for subscriptions | MCP SSE support | To verify |
| Session cleanup | DELETE `/v1/mcp` closes session | Standard MCP lifecycle | To verify |

## Auth Compatibility

| Auth Method | How It Works | OpenClaw Config |
|-------------|-------------|-----------------|
| Anonymous mode | `AIMEAT_ANONYMOUS=true` — no auth required | No headers needed |
| Initial OTK | `POST /v1/auth/initial-otk` → embed in config | `Authorization: Bearer otk-...` header |
| JWT | `POST /v1/auth/token` → short-lived token | `Authorization: Bearer <jwt>` header |
| Inline MCP auth | `clientInfo.gaii` in MCP initialize request | If OpenClaw supports MCP clientInfo |

## Tool Call Behavior

AIMEAT MCP tools return JSON in `text` content blocks. All responses are structured JSON:

```json
{
  "content": [{
    "type": "text",
    "text": "{ \"key\": \"...\", \"value\": \"...\", \"version\": 1 }"
  }]
}
```

Error responses set `isError: true` and include a descriptive message in `text`.

## Concurrency

- Each MCP session gets its own `StreamableHTTPServerTransport` instance
- Sessions are isolated by `mcp-session-id`
- Multiple concurrent tool calls within one session are serialized by the transport
- Multiple sessions (e.g., multiple OpenClaw agents) work independently
- Memory writes use version-based optimistic concurrency (PUT with version → 409 on conflict)

## Known Considerations

1. **OTK single-use**: Initial OTKs expire after first use + grace period. For long-running OpenClaw agents, prefer JWT auth with token refresh.
2. **Rate limiting**: AIMEAT enforces per-agent rate limits. Check `X-RateLimit-*` response headers.
3. **File size limit**: `aimeat_storage_upload` has a 10MB limit (configurable via `AIMEAT_STORAGE_MAX_FILE_SIZE_MB`).
4. **Memory value size**: Default max is 1MB per value (configurable via `AIMEAT_MEMORY_MAX_VALUE_SIZE_KB`).

## Verification Checklist

Run these manual tests with OpenClaw connected to a local AIMEAT node:

- [ ] MCP session initializes successfully (tools/list returns 18 tools)
- [ ] `aimeat_memory_write` + `aimeat_memory_read` roundtrip works
- [ ] `aimeat_memory_list` returns written entries
- [ ] `aimeat_catalogue_search` returns results (if actions exist)
- [ ] `aimeat_board_post` + `aimeat_board_read` roundtrip works
- [ ] `aimeat_wallet_balance` returns balance info
- [ ] `aimeat_work_inbox` returns empty or pending items
- [ ] Auth with Initial OTK succeeds (tool calls authenticate)
- [ ] Anonymous mode works without any auth headers
- [ ] Concurrent tool calls from OpenClaw do not cause errors
- [ ] SSE resource subscriptions deliver notifications on memory write
- [ ] Session cleanup (DELETE `/v1/mcp`) terminates cleanly

## AIMEAT E2E Test Reference

The file `test/e2e-mcp.ts` validates the full MCP lifecycle including:
- OAuth 2.1 client registration and token exchange
- MCP session initialize → tools/list → tools/call
- All 14 user tools + 4 admin tools
- Resource reads (memory, wallet, storage)
- SSE stream validation

Use this as a baseline for comparing OpenClaw client behavior.

---

*Created: 2026-03-04 — REQ-001*
