# SDK and transport compatibility

Known differences between the current SDKs, CLI, standalone MCP server, and dedicated daemon.

Source: https://docs.minds.sh/docs/developers/compatibility



The repositories contain useful client surfaces, but source signatures alone do not prove that a call works against the currently configured daemon. This page records concrete differences found in the 2026-09-12 source snapshot so integrations can use the exact HTTP contract where needed.

## Authentication [#authentication]

| Interface                     | What the source sends       | Current limitation                                                                                                    |
| ----------------------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| TypeScript `SDKConfig.token`  | `Authorization: Bearer ...` | High-level clients do not automatically set `x-akasha-capability`; public `HttpClient.request` supports extra headers |
| Python `AkashaClient.api_key` | `Authorization: Bearer ...` | Does not set management `x-api-key` or instance capability header; explicit `httpx` can supply them                   |
| Go `Config.APIKey`            | `Authorization: Bearer ...` | Default transport has no public additional-header option                                                              |
| Rust `HttpConfig.token`       | `Authorization: Bearer ...` | Default transport has no public capability-header option                                                              |
| cogs `AKASHA_TOKEN`           | Rust SDK Bearer transport   | A token value alone does not satisfy capability-required instance requests                                            |
| Minds dashboard Akasha proxy  | `x-akasha-capability`       | Uses the signed-in browser and authorized active-instance context                                                     |

The daemon checks `x-akasha-capability` when `AKASHA_REQUIRE_CAPABILITY` is enabled. If a deployment also enables legacy JWT verification, that check is additional. Do not disable server authentication to make an old client example pass.

## Request and response differences [#request-and-response-differences]

| Operation                                   | Client behavior                             | Inspected daemon contract                                                       |
| ------------------------------------------- | ------------------------------------------- | ------------------------------------------------------------------------------- |
| TypeScript cognitive remember/recall/forget | Per-tool paths under `/v1/mcp/tools/<name>` | `POST /v1/mcp/tools/call` with `{name, arguments}`                              |
| TypeScript list tools                       | `GET /v1/mcp/tools`                         | `POST /v1/mcp/tools/list` with `{}`                                             |
| TypeScript hybrid retrieval                 | Sends `query`, expects `results`            | Sends `text`, optional `limit`/`chunk`; response has `rows`                     |
| Python hybrid retrieval                     | Sends `query`/`top_k`, expects `results`    | Same `text`/`limit`/`rows` daemon contract                                      |
| TypeScript/Python episodic insertion        | Flat event fields                           | Daemon expects an `event` wrapper                                               |
| Rust/cogs episodic store                    | Sends `raw_from` and `tags`                 | Daemon expects an `event` wrapper                                               |
| Python episodic search                      | Expects `{events:...}`                      | Daemon returns a bare array                                                     |
| Rust/cogs episodic search                   | Sends `query` and `limit`, expects array    | Matches the inspected payload shape; authentication compatibility still applies |
| Rust/cogs hybrid retrieval                  | Sends `text` and `limit`                    | Matches the inspected payload shape; authentication compatibility still applies |

Use [Connect to your Mind](/docs/developers/quickstart) for an explicit request. A tool response has `content`, `is_error`, and `result`; check `is_error` even after HTTP success.

## MCP hosts and persistence [#mcp-hosts-and-persistence]

The separate `akasha-mcp` binary supports standard MCP transports, but its default standalone constructor uses `InMemoryBackend`. Setting `--endpoint` does not replace that backend in this source version. A host can test tools during that process's lifetime, but the configuration is not a verified persistent connection to the dedicated Mind.

The cogs `mcp setup-claude` and `mcp setup-cursor` helpers currently generate a command containing `akasha mcp serve`; the CLI's `McpAction` enum has no `serve` subcommand. Use the manual, explicitly local demonstration setup in [Agent integrations](/docs/agents), or the direct HTTP integration for durable instance access.

`cogs mcp test` creates a fresh in-memory backend for each invocation. Two separate invocations do not share the memory created by the first.

## Source versus release [#source-versus-release]

These findings do not imply identical behavior in every published release. Pin the SDK, record the daemon revision and enabled services, and validate the exact method your application will use. When a fix lands, repeat the request and result checks before removing a compatibility note.

Evidence: `minds-ts-sdk/src/index.ts`; `minds-python-sdk/akasha/runtime/memory.py`; `minds-go-sdk/akasha/client.go`; `minds-rust-sdk/src/{clients,transport}.rs`; `minds-cli/src/{main,mcp}.rs`; `akasha-daemon/src/main.rs`; `akasha/mcp/src/{server,tools/mod}.rs`.