# gRPC, Arrow Flight, and MCP The instance's additional protocol surfaces, exact message definitions, service dependencies, and access boundaries. Source: https://docs.minds.sh/docs/api/instance/protocols The daemon starts multiple listeners when their services are enabled. They do not share one authentication implementation. Use the HTTP capability contract for the customer-facing instance API; the current gRPC and Flight listeners are internal transport surfaces whose source lacks equivalent signed-request verification. | Surface | Default listener | Startup dependency | | --------------------- | ------------------ | ------------------------------------------------------------ | | HTTP | `0.0.0.0:8080` | Main daemon router | | Daemon gRPC | `0.0.0.0:50053` | `enable_conductor` and an initialized cognitive orchestrator | | SNN coordination gRPC | Same gRPC listener | A federation coordinator is present | | Arrow Flight | `0.0.0.0:50054` | `enable_flight` and an initialized database | | Router service | `0.0.0.0:50051` | `enable_router`; a separate router crate owns this protocol | | Conductor HTTP | `0.0.0.0:8082` | Separate conductor router and authentication configuration | The address overrides are `AKASHA_HTTP_ADDR`, `AKASHA_GRPC_ADDR`, `AKASHA_FLIGHT_ADDR`, `AKASHA_ROUTER_ADDR`, and `AKASHA_CONDUCTOR_ADDR`. These are listener defaults, not published hosted addresses. ## Daemon gRPC [#daemon-grpc] Service name: `akasha.daemon.v1.AkashaDaemon`. | RPC | Request | Response | Behavior | | --------------------- | ---------------------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------- | | Health | Empty | HealthResponse | Returns the daemon service's health state. | | SqlQuery | SqlQueryRequest | SqlQueryResponse | Executes SQL and returns one JSON string per row. | | ProcessCognitiveEvent | CognitiveProcessEventRequest | CognitiveProcessEventResponse | Parses the event payload JSON and passes it to the orchestrator. | | GetCognitiveMetrics | CognitiveMetricsRequest | CognitiveMetricsResponse | Returns metrics encoded as a JSON string. | | QueryCognitiveContext | CognitiveContextQueryRequest | CognitiveContextQueryResponse | Returns retrieved context encoded as a JSON string. | | TrainSupervised | TrainSupervisedRequest | TrainSupervisedResponse | Submits numeric feature/label training samples with optional training parameters. | | TrainHrm | TrainHrmRequest | TrainHrmResponse | Submits domain/keyspace-based HRM training configuration. Deprecated inputs/targets fields remain in the schema. | `CapabilityContext` is a protobuf message containing namespace, actor, action, keyspace, and expiry fields. In this source, `scoped_db_from_context` converts it directly into a payload and requests a scoped database. If it is absent, the handler can use the default database. The tonic startup path does not install a signature-verifying interceptor or TLS configuration. This is a source implementation gap, not an authenticated public capability credential. Network access must be controlled by the instance operator until that boundary is implemented. The exact protobuf files are included in the [protocol wire definitions](/docs/api/instance/protocol-wire-definitions). Runtime source: `akasha-daemon/src/grpc.rs`; listener wiring: `serve_grpc` in `akasha-daemon/src/main.rs`. ## SNN coordination gRPC [#snn-coordination-grpc] Service name: `akasha.snn.SnnCoordination`. | RPC | Request | Response | | ------------------- | ----------------- | -------------------- | | RegisterAgent | AgentRegistration | RegistrationResponse | | SubmitWeightUpdates | WeightUpdateBatch | UpdateResponse | | GetGlobalParameters | ParameterRequest | GlobalParameters | | PropagateSpikeEvent | SpikeEvent | PropagationResponse | | QueryCapabilities | CapabilityQuery | CapabilityResponse | These messages carry agent IDs, ensemble/connection identifiers, numeric parameter arrays, capabilities, visibility, and timestamps. They call the shared federation coordinator. The listener has the same interceptor gap described above; a supplied agent ID is not proof of authenticated identity. ## Arrow Flight [#arrow-flight] The Flight implementation is a SQL query transport built on the standard `arrow.flight.protocol.FlightService`. It is not a complete Flight SQL command implementation. Create a ticket or a command descriptor whose bytes contain UTF-8 JSON: ```json {"sql":"SELECT 1"} ``` | Flight method | Current behavior | | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | Handshake | Returns protocol version `0` and an empty payload. No credential verification occurs. | | ListFlights | Empty stream. | | GetFlightInfo | Validates a non-empty UTF-8 JSON command, returns that command as a ticket, unknown record/byte counts (`-1`), and an empty schema field. | | GetSchema | Executes the SQL using the default database, then returns encoded schema data from the first batch, or an empty schema when no batches exist. | | DoGet | Parses the SQL ticket, executes it against the default database, and streams encoded Arrow record batches. | | PollFlightInfo | `UNIMPLEMENTED`. | | DoPut | `UNIMPLEMENTED`. | | DoExchange | `UNIMPLEMENTED`. | | DoAction | `UNIMPLEMENTED`. | | ListActions | Empty stream. | Missing command/ticket bytes, invalid UTF-8, and malformed JSON return `INVALID_ARGUMENT`. Missing database state returns `UNAVAILABLE`; SQL and encoding errors map to `INTERNAL` in this transport. Unlike the HTTP request path, Flight calls `state.require_db()` rather than deriving a database from a signed namespace capability. Its server builder installs no authentication interceptor. Do not infer tenant isolation or public API authorization from a successful Flight handshake. Source: `akasha-daemon/src/flight.rs` and `serve_flight` in `akasha-daemon/src/main.rs`. ## MCP over the instance HTTP API [#mcp-over-the-instance-http-api] The daemon exposes the MCP tool registry through ordinary JSON HTTP operations: ```http POST /v1/mcp/tools/list Content-Type: application/json x-akasha-capability: {} ``` The response has a `tools` array. Each tool description contains `name`, `description`, and `inputSchema`. Fetch that list from the configured instance because enabled profiles and disabled-tool filters alter the registry. ```http POST /v1/mcp/tools/call Content-Type: application/json x-akasha-capability: { "name": "recall", "arguments": {"query": "What did we decide about the launch?"} } ``` These endpoints expect the shown REST body, not a JSON-RPC envelope. Their namespace and actor come from authenticated request authority. The optional `namespace` request field is for Cambium recall augmentation; it is not a substitute for that authority. The public authority map includes `remember`, `store_episode`, `store_fact`, `store_procedure`, `run_procedure`, `recall`, `search_similar`, `search_temporal`, `forget`, `introspect`, `reflect`, `link_concepts`, `namespace_status`, `tool_profile_status`, `configure_index`, `raw_query`, `batch_import`, and `export_memories`. A registered tool without a public authority mapping is rejected with `403`. `raw_query` and `batch_import` require an explicit non-empty `keyspace`; export requires explicit `memory_types`. Vault export is explicitly rejected by the current HTTP backend. The connection-information route currently labels its registry `embedded`/`stdio`; that value does not create a stdio transport on the HTTP listener. A separate MCP executable under `akasha/mcp` provides its own stdio/SSE transport. Do not treat the daemon's registry wrapper as a generic remote MCP connection URL. See [MCP HTTP operations](/docs/api/instance/mcp) for request/response assembly and [protocol wire definitions](/docs/api/instance/protocol-wire-definitions) for source tool schemas. Source: `akasha-daemon/src/mcp/handlers.rs`, `akasha-daemon/src/request_authority.rs`, and `akasha/mcp/src/tools/mod.rs`.