# Mcp

Every registered mcp instance operation, with source-derived inputs, outputs, access policy, and errors.

Source: https://docs.minds.sh/docs/api/instance/mcp



This reference covers **6 HTTP operations** registered by the Akasha daemon. Call these paths on your instance base URL. See [authentication](/docs/api/instance/authentication), [errors](/docs/api/instance/errors), and [coverage](/docs/api/instance/coverage) before integrating.

| Method | Path                 | Operation                                 |
| ------ | -------------------- | ----------------------------------------- |
| `POST` | `/v1/mcp/tools/list` | [Mcp tools list](#post-v1-mcp-tools-list) |
| `POST` | `/v1/mcp/tools/call` | [Mcp tools call](#post-v1-mcp-tools-call) |
| `GET`  | `/v1/mcp/health`     | [Mcp health](#get-v1-mcp-health)          |
| `GET`  | `/v1/mcp/connection` | [Mcp connection](#get-v1-mcp-connection)  |
| `GET`  | `/v1/mcp/stats`      | [Mcp stats](#get-v1-mcp-stats)            |
| `GET`  | `/v1/mcp/history`    | [Mcp history](#get-v1-mcp-history)        |

<a id="post-v1-mcp-tools-list" />

## POST `/v1/mcp/tools/list` [#post-v1mcptoolslist]

List available MCP tools.

| Availability         | Source contract                            |
| -------------------- | ------------------------------------------ |
| Registration         | `config.enable_mcp`                        |
| Runtime service      | `mcp`                                      |
| Handler dependencies | See handler source and return expressions. |

**Access:** Daemon authentication and capability namespace authority; memory-domain permissions apply where mapped.

### Request [#request]

**Json** — `McpToolsListRequest`

```rust
struct McpToolsListRequest {}
```

### Response [#response]

**Declared return:** `Result<impl IntoResponse, DaemonError>`

The following are the exact JSON construction expressions in the handler. Values such as `rows`, `result`, and delegated types are runtime values, not literal example payloads.

```rust
serde_json::json!({
        "tools": tool_list,
    })
```

### Errors and validation [#errors-and-validation]

Directly referenced error variants: none in the handler body. Middleware and delegated services can return additional errors described in the shared error reference.

<Accordions>
  <Accordion title="Inspect implementation">
    This exact source excerpt includes validation, defaults, delegated calls, and response assembly.

    ```rust
    async fn mcp_tools_list(
        State(state): State<AppState>,
        Json(_req): Json<McpToolsListRequest>,
    ) -> Result<impl IntoResponse, DaemonError> {
        let tools = require_mcp(&state)?;
        let tool_list = tools.list_tools();
        Ok(Json(serde_json::json!({
            "tools": tool_list,
        })))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/mcp/handlers.rs:115`. Registration: `akasha-daemon/src/main.rs:4732`.

<a id="post-v1-mcp-tools-call" />

## POST `/v1/mcp/tools/call` [#post-v1mcptoolscall]

Call an MCP tool. The namespace and capabilities are derived from the authenticated capability token (injected by the auth layer), NOT from the request body.  This prevents callers from escalating their privileges by sending an arbitrary namespace or capability set in the JSON payload.

| Availability         | Source contract                            |
| -------------------- | ------------------------------------------ |
| Registration         | `config.enable_mcp`                        |
| Runtime service      | `mcp`                                      |
| Handler dependencies | See handler source and return expressions. |

**Access:** Daemon authentication and capability namespace authority; memory-domain permissions apply where mapped. Handler additionally checks require(required\_action, Some(required\_keyspace)).

### Request [#request-1]

**Json** — `McpToolsCallRequest`

| Field       | Rust type        | Required on input         | Notes                                                                                    |
| ----------- | ---------------- | ------------------------- | ---------------------------------------------------------------------------------------- |
| `name`      | `String`         | Yes                       | The name of the tool to call                                                             |
| `arguments` | `JsonValue`      | No; optional or defaulted | Arguments to pass to the tool Serde: `default`                                           |
| `namespace` | `Option<String>` | No; optional or defaulted | Optional caller-supplied namespace used by Cambium recall augmentation. Serde: `default` |

```rust
struct McpToolsCallRequest {
    /// The name of the tool to call
    pub name: String,
    /// Arguments to pass to the tool
    #[serde(default)]
    pub arguments: JsonValue,
    /// Optional caller-supplied namespace used by Cambium recall augmentation.
    #[serde(default)]
    pub namespace: Option<String>,
}
```

**JSON field accesses in handler:** `memory_types`. Nested lookups are included; this list alone does not establish requiredness.

### Response [#response-1]

**Declared return:** `Result<impl IntoResponse, DaemonError>`

The following are the exact JSON construction expressions in the handler. Values such as `rows`, `result`, and delegated types are runtime values, not literal example payloads.

```rust
result
```

### Errors and validation [#errors-and-validation-1]

Directly referenced error variants: `Internal`, `InvalidRequest`. Middleware and delegated services can return additional errors described in the shared error reference.

<Accordions>
  <Accordion title="Inspect implementation">
    This exact source excerpt includes validation, defaults, delegated calls, and response assembly.

    ```rust
    async fn mcp_tools_call(
        State(state): State<AppState>,
        Extension(authority): Extension<RequestAuthority>,
        Json(req): Json<McpToolsCallRequest>,
    ) -> Result<impl IntoResponse, DaemonError> {
        let requirements = mcp_tool_requirements(&req.name, &req.arguments)?;
        for (required_action, required_keyspace) in requirements {
            authority.require(required_action, Some(required_keyspace))?;
        }
        if req.name.eq_ignore_ascii_case("export_memories")
            && req
                .arguments
                .get("memory_types")
                .and_then(serde_json::Value::as_array)
                .is_some_and(|domains| {
                    domains.iter().any(|domain| {
                        domain
                            .as_str()
                            .is_some_and(|value| value.eq_ignore_ascii_case("vault"))
                    })
                })
        {
            return Err(DaemonError::InvalidRequest(
                "vault export is not supported by the current MCP export backend".to_string(),
            ));
        }

        // Emit usage based on MCP tool name
        let op_type = mcp_tool_to_op_type(&req.name);
        state.usage_emitter.emit_cognitive_op(op_type);

        let tools = require_mcp(&state)?;

        // Use the authenticated namespace from the capability token, never the request body.
        let ns_id = authority.namespace().to_hex();
        let mut context = akasha_mcp::NamespaceContext::new(ns_id.as_str(), authority.actor());

        // Derive MCP capabilities from the token's granted actions instead of
        // blindly granting all tier1 + tier2.
        context.identity.capabilities = actions_to_mcp_capabilities(authority.actions());

        let result: serde_json::Value = tools
            .call(&req.name, &req.arguments, &context)
            .await
            .map_err(|e| DaemonError::Internal(format!("MCP tool error: {e}")))?;
        let result = if req.name.eq_ignore_ascii_case("recall") {
            crate::cambium::merge_cambium_recall_result(
                state.cambium_projection_store(),
                result,
                &req.arguments,
                req.namespace.as_deref(),
            )
            .await
        } else {
            result
        };

        // Record in mcp_call_history
        {
            let entry = serde_json::json!({
                "tool": &req.name,
                "arguments": &req.arguments,
                "result": &result,
                "timestamp": chrono::Utc::now().to_rfc3339()
            });
            let mut history = state.mcp_call_history.write().await;
            if history.len() >= 100 {
                history.pop_front();
            }
            history.push_back(entry);
        }

        Ok(Json(result))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/mcp/handlers.rs:132`. Registration: `akasha-daemon/src/main.rs:4733`.

<a id="get-v1-mcp-health" />

## GET `/v1/mcp/health` [#get-v1mcphealth]

MCP service health endpoint.

| Availability         | Source contract                            |
| -------------------- | ------------------------------------------ |
| Registration         | `config.enable_mcp`                        |
| Runtime service      | `mcp`                                      |
| Handler dependencies | See handler source and return expressions. |

**Access:** Daemon authentication and capability namespace authority; memory-domain permissions apply where mapped.

### Request [#request-2]

No typed JSON, query, or path extractor is declared in the handler signature. Headers or request objects may still be consumed; the signature below is authoritative.

### Response [#response-2]

**Declared return:** `Result<impl IntoResponse, DaemonError>`

The following are the exact JSON construction expressions in the handler. Values such as `rows`, `result`, and delegated types are runtime values, not literal example payloads.

```rust
serde_json::json!({
        "status": "healthy",
        "tool_count": tools.tool_count(),
    })
```

### Errors and validation [#errors-and-validation-2]

Directly referenced error variants: none in the handler body. Middleware and delegated services can return additional errors described in the shared error reference.

<Accordions>
  <Accordion title="Inspect implementation">
    This exact source excerpt includes validation, defaults, delegated calls, and response assembly.

    ```rust
    async fn mcp_health(State(state): State<AppState>) -> Result<impl IntoResponse, DaemonError> {
        let tools = require_mcp(&state)?;
        Ok(Json(serde_json::json!({
            "status": "healthy",
            "tool_count": tools.tool_count(),
        })))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/mcp/handlers.rs:208`. Registration: `akasha-daemon/src/main.rs:4734`.

<a id="get-v1-mcp-connection" />

## GET `/v1/mcp/connection` [#get-v1mcpconnection]

Mcp connection

| Availability         | Source contract                            |
| -------------------- | ------------------------------------------ |
| Registration         | `config.enable_mcp`                        |
| Runtime service      | `mcp`                                      |
| Handler dependencies | See handler source and return expressions. |

**Access:** Daemon authentication and capability namespace authority; memory-domain permissions apply where mapped.

### Request [#request-3]

No typed JSON, query, or path extractor is declared in the handler signature. Headers or request objects may still be consumed; the signature below is authoritative.

### Response [#response-3]

**Declared return:** `Result<impl IntoResponse, DaemonError>`

The following are the exact JSON construction expressions in the handler. Values such as `rows`, `result`, and delegated types are runtime values, not literal example payloads.

```rust
serde_json::json!({
        "endpoint": "embedded",
        "protocol": "stdio",
        "status": if connected { "connected" } else { "disconnected" },
        "lastPing": chrono::Utc::now().to_rfc3339(),
        "version": "1.0",
        "capabilities": ["tools"]
    })
```

### Errors and validation [#errors-and-validation-3]

Directly referenced error variants: none in the handler body. Middleware and delegated services can return additional errors described in the shared error reference.

<Accordions>
  <Accordion title="Inspect implementation">
    This exact source excerpt includes validation, defaults, delegated calls, and response assembly.

    ```rust
    async fn mcp_connection(State(state): State<AppState>) -> Result<impl IntoResponse, DaemonError> {
        state.record_http_request();
        let connected = state.mcp_tools.is_some();
        Ok(Json(serde_json::json!({
            "endpoint": "embedded",
            "protocol": "stdio",
            "status": if connected { "connected" } else { "disconnected" },
            "lastPing": chrono::Utc::now().to_rfc3339(),
            "version": "1.0",
            "capabilities": ["tools"]
        })))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:10552`. Registration: `akasha-daemon/src/main.rs:4735`.

<a id="get-v1-mcp-stats" />

## GET `/v1/mcp/stats` [#get-v1mcpstats]

Mcp stats

| Availability         | Source contract                            |
| -------------------- | ------------------------------------------ |
| Registration         | `config.enable_mcp`                        |
| Runtime service      | `mcp`                                      |
| Handler dependencies | See handler source and return expressions. |

**Access:** Daemon authentication and capability namespace authority; memory-domain permissions apply where mapped.

### Request [#request-4]

**Implementation limit:** Only tool\_count is read from the registry; callsToday, avgLatencyMs, errorRate, and topTools are fixed placeholder values.

No typed JSON, query, or path extractor is declared in the handler signature. Headers or request objects may still be consumed; the signature below is authoritative.

### Response [#response-4]

**Declared return:** `Result<impl IntoResponse, DaemonError>`

The following are the exact JSON construction expressions in the handler. Values such as `rows`, `result`, and delegated types are runtime values, not literal example payloads.

```rust
serde_json::json!({
        "totalTools": tool_count,
        "callsToday": 0,
        "avgLatencyMs": 0,
        "errorRate": 0,
        "topTools": []
    })
```

### Errors and validation [#errors-and-validation-4]

Directly referenced error variants: none in the handler body. Middleware and delegated services can return additional errors described in the shared error reference.

<Accordions>
  <Accordion title="Inspect implementation">
    This exact source excerpt includes validation, defaults, delegated calls, and response assembly.

    ```rust
    async fn mcp_stats(State(state): State<AppState>) -> Result<impl IntoResponse, DaemonError> {
        state.record_http_request();
        let tool_count = state
            .mcp_tools
            .as_ref()
            .map(|t| t.tool_count())
            .unwrap_or(0);
        Ok(Json(serde_json::json!({
            "totalTools": tool_count,
            "callsToday": 0,
            "avgLatencyMs": 0,
            "errorRate": 0,
            "topTools": []
        })))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:10566`. Registration: `akasha-daemon/src/main.rs:4736`.

<a id="get-v1-mcp-history" />

## GET `/v1/mcp/history` [#get-v1mcphistory]

Mcp history

| Availability         | Source contract                            |
| -------------------- | ------------------------------------------ |
| Registration         | `config.enable_mcp`                        |
| Runtime service      | `mcp`                                      |
| Handler dependencies | See handler source and return expressions. |

**Access:** Daemon authentication and capability namespace authority; memory-domain permissions apply where mapped.

### Request [#request-5]

No typed JSON, query, or path extractor is declared in the handler signature. Headers or request objects may still be consumed; the signature below is authoritative.

### Response [#response-5]

**Declared return:** `Result<impl IntoResponse, DaemonError>`

The following are the exact JSON construction expressions in the handler. Values such as `rows`, `result`, and delegated types are runtime values, not literal example payloads.

```rust
serde_json::json!(entries)
```

### Errors and validation [#errors-and-validation-5]

Directly referenced error variants: none in the handler body. Middleware and delegated services can return additional errors described in the shared error reference.

<Accordions>
  <Accordion title="Inspect implementation">
    This exact source excerpt includes validation, defaults, delegated calls, and response assembly.

    ```rust
    async fn mcp_history(State(state): State<AppState>) -> Result<impl IntoResponse, DaemonError> {
        state.record_http_request();
        let history = state.mcp_call_history.read().await;
        let entries: Vec<serde_json::Value> = history.iter().cloned().collect();
        Ok(Json(serde_json::json!(entries)))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:10583`. Registration: `akasha-daemon/src/main.rs:4737`.