> ## Documentation Index
> Fetch the complete documentation index at: https://docs.solya.app/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP gateway

> Connect an AI agent to Solya through the Model Context Protocol — what the gateway is, its tools, and how it maps to the API.

The **Solya MCP gateway** lets an AI agent (Claude, Cursor, or any
[MCP](https://modelcontextprotocol.io) client) drive Solya through the
[REST API](/en/developers/overview) — discover endpoints, inspect them, and call them — all
behind three generic tools.

## How it works

The gateway is a hosted service in front of the Solya API. It reads the live
[OpenAPI spec](/en/developers/overview) at runtime (so it never drifts from the API) and
exposes every operation through three tools:

| Tool                 | What it does                                                                                                                                                   |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `search_operations`  | Keyword-search the API's operations; returns a compact list (`operation_id`, method, path, summary, tags). Results are filtered to what your token can access. |
| `describe_operation` | Return the full schema of one operation — method, path, parameters, request/response bodies, required auth.                                                    |
| `invoke_operation`   | Execute an operation — fills path placeholders, adds query params and a JSON body, attaches your token, and returns the HTTP status + parsed response.         |

A typical agent flow:

<Steps>
  <Step title="Search">
    `search_operations("rebalance plans")` → find the relevant endpoint.
  </Step>

  <Step title="Describe">
    `describe_operation("listRebalancePlans")` → get its exact schema.
  </Step>

  <Step title="Invoke">
    `invoke_operation("listRebalancePlans", query: { page: 1 })` → fetch the data.
  </Step>
</Steps>

## Authentication & scope

The gateway is a **thin proxy** — it stores no secrets. Each client sends its own
[service-account token](/en/developers/authentication) (`solya_sa_…`) as a bearer header,
which the gateway forwards to the API. Therefore:

* Everything runs **as your token**: same organization scope, same permissions. The agent
  can only do what the token's permissions allow (the API still enforces `403`).
* `search_operations` hides operations your token can't use (ergonomic, not a security
  boundary — the API is the boundary).
* Responses are the standard API envelope: `{ "success": true, "data": … }` or
  `{ "success": false, "errorCode": … }` (see [Error codes](/en/developers/error-codes)).

<Note>
  Because the gateway reflects the OpenAPI spec, **any** Solya endpoint your token can call
  is reachable through `invoke_operation` — no per-tool wiring. To connect a client, see
  [Connect a client](/en/mcp/connect).
</Note>