# Agents and MCP

Read spend and savings per agent, call tools through the governed MCP gateway, and run the assistant’s read tools.

[All of the API reference](https://www.azothos.ai/docs/api)

> Route summaries and field names are written in English, here and in the file.

## /api/v1/agents

### GET /api/v1/agents

Spend and savings per agent

- **Authentication** — API key
- **Key scope** — `agents:read`
- **Parameters** — `days`
- **Answers** — `200` · `400` [validation_failed](https://www.azothos.ai/docs/errors#validation_failed) · `401` [api_key_missing](https://www.azothos.ai/docs/errors#api_key_missing), [api_key_invalid](https://www.azothos.ai/docs/errors#api_key_invalid) · `403` [api_key_scope_denied](https://www.azothos.ai/docs/errors#api_key_scope_denied), [api_key_role_denied](https://www.azothos.ai/docs/errors#api_key_role_denied), [ip_not_allowed](https://www.azothos.ai/docs/errors#ip_not_allowed), [plan_required](https://www.azothos.ai/docs/errors#plan_required) · `429`

## /api/v1/mcp

### GET /api/v1/mcp

Not used — the MCP gateway opens no stream (405)

- **Authentication** — API key
- **Key scope** — `agents:write`
- **Module** — Served where the deployment runs `FEATURE_MCP_GATEWAY`.
- **Answers** — `405`

### POST /api/v1/mcp

The governed MCP gateway (Streamable HTTP, tools only)

- **Authentication** — API key
- **Key scope** — `agents:write`
- **Module** — Served where the deployment runs `FEATURE_MCP_GATEWAY`.
- **Body** — `application/json`
- **Answers** — `200` · `202` · `400` · `401` [api_key_missing](https://www.azothos.ai/docs/errors#api_key_missing), [api_key_invalid](https://www.azothos.ai/docs/errors#api_key_invalid) · `403` [key_not_bound_to_agent](https://www.azothos.ai/docs/errors#key_not_bound_to_agent), [origin_not_allowed](https://www.azothos.ai/docs/errors#origin_not_allowed), [api_key_scope_denied](https://www.azothos.ai/docs/errors#api_key_scope_denied), [plan_required](https://www.azothos.ai/docs/errors#plan_required) · `429` · `500` [internal_error](https://www.azothos.ai/docs/errors#internal_error) · `501` [feature_disabled](https://www.azothos.ai/docs/errors#feature_disabled) · `503` [feature_disabled](https://www.azothos.ai/docs/errors#feature_disabled), [service_unavailable](https://www.azothos.ai/docs/errors#service_unavailable)

### DELETE /api/v1/mcp

Not used — the MCP gateway keeps no session (405)

- **Authentication** — API key
- **Key scope** — `agents:write`
- **Module** — Served where the deployment runs `FEATURE_MCP_GATEWAY`.
- **Answers** — `405`

## /api/v1/insights

### POST /api/v1/insights/{tool}

Run one of the assistant's read tools

- **Authentication** — API key
- **Key scope** — `insights:read`
- **Module** — Served where the deployment runs `FEATURE_ASSISTANT`.
- **Parameters** — `tool` (required)
- **Body** — `input` · `locale`
- **Answers** — `200` · `400` [validation_failed](https://www.azothos.ai/docs/errors#validation_failed) · `401` [api_key_missing](https://www.azothos.ai/docs/errors#api_key_missing), [api_key_invalid](https://www.azothos.ai/docs/errors#api_key_invalid) · `403` [assistant_disabled](https://www.azothos.ai/docs/errors#assistant_disabled), [api_key_scope_denied](https://www.azothos.ai/docs/errors#api_key_scope_denied), [plan_required](https://www.azothos.ai/docs/errors#plan_required) · `404` [unknown_tool](https://www.azothos.ai/docs/errors#unknown_tool) · `429` · `500` [internal_error](https://www.azothos.ai/docs/errors#internal_error) · `501` [feature_disabled](https://www.azothos.ai/docs/errors#feature_disabled) · `503` [service_unavailable](https://www.azothos.ai/docs/errors#service_unavailable)
