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

# MCP server

> Connect a coding agent or AI client to Sazabi over the Model Context Protocol using the search and execute tools.

The Sazabi MCP server exposes the Sazabi API to any Model Context Protocol client — a coding agent, an AI IDE, or a custom client. It lets that client query your logs, investigate issues, and run the Sazabi agent through the same operations the API offers.

This page is the protocol reference. For copy-paste setup for a specific client (Claude Code, Cursor, Codex, ChatGPT, and others), see [Connect your coding agent](https://docs.sazabi.com/get-started/coding-agents.md), which owns the per-client configuration.

## Server URL

Connect over Streamable HTTP:

```txt theme={"system"}
https://mcp.sazabi.com/mcp
```

## Authentication

Authenticate with a **secret key**. Create one in the dashboard under [**Settings > Secret keys**](https://app.sazabi.com/settings/secret-keys) or with `sazabi secret-keys create <name>`. Send it in the `X-Sazabi-Secret-Key` header. A secret key sent as an `Authorization: Bearer` token is rejected; that header is only for OAuth tokens.

```json theme={"system"}
{
  "mcpServers": {
    "sazabi": {
      "type": "http",
      "url": "https://mcp.sazabi.com/mcp",
      "headers": {
        "X-Sazabi-Secret-Key": "sazabi_secret_your_secret_key"
      }
    }
  }
}
```

The server also supports OAuth: a client that implements the MCP OAuth flow can connect with a browser sign-in and no key at all. Use OAuth where your client supports it; a secret key works in every client.

Secret keys are organization-scoped by default and grant read/write access. Keep them out of source control and rotate them if exposed.

## The two tools

The server exposes exactly two tools — `search` and `execute` — rather than one tool per feature. New API operations become reachable through `search` automatically, so the tool surface stays stable as the API grows.

### search

Discovers the Sazabi API operations and connected MCP tools the caller can run. Results are compact by default — each hit carries a copy-paste `name` (the value to pass to `execute`) and a description.

* `query` — free-text query matched against operation ids and tool descriptions. Omit or leave empty to list connected MCP connectors.
* `namespace` — a connector key from a previous search, or `sazabi` for only the Sazabi API catalog.
* `includeInputSchema` — set to `true` only after selecting a hit; pass its namespace and copy its full `name` into `query`. The exact lookup returns at most one hit with its input JSON schema and never substitutes a fuzzy match.
* `limit` / `offset` — pagination over compact hits (capped at 20 per page).

### execute

Invokes one search hit. Copy the `name` from `search` and pass an `arguments` object matching that hit's input schema:

* `name` — a `search` hit's name, either `sazabi/<operationId>` (a Sazabi API operation) or `<connectionKey>/<toolName>` (a connected MCP connector's tool).
* `arguments` — an object matching the hit's input schema.
* `projectId` — optional; targets a specific project's connectors when the credential does not already select one.

The typical flow is: call `search` to find the tool you need, repeat the search with its namespace, copy its full `name` into `query`, and set `includeInputSchema: true` to load that one schema, then call `execute` with the returned `name` and matching `arguments`.

### Deferred operations

Some operations start long-running Sazabi agent work — for example creating a thread or appending a message. For those, `execute` waits a short time for the run to finish. If it does not complete in that window, the response reports the run as incomplete and returns a run identifier. Call `execute` again with the `runs.get` operation and that run identifier to poll for the result.

## What you can do

Because every API operation is reachable through `execute`, the MCP server can do everything the API can — query logs, search and manage issues, create and continue agent threads, and inspect projects. Run `search` with an empty query to list your connected MCP connectors, or with `namespace: "sazabi"` to browse the Sazabi operation catalog.

For the full list of operations and their fields, see [API reference](https://docs.sazabi.com/reference/api.md).

## Further reading

> [card] [Connect your coding agent](https://docs.sazabi.com/get-started/coding-agents.md)
>
> Per-client setup for Claude Code, Cursor, Codex, and more.

> [card] [API reference](https://docs.sazabi.com/reference/api.md)
>
> Every operation the execute tool can run.

> [card] [Secret keys](https://docs.sazabi.com/guides/administer/keys.md)
>
> Create and manage the secret key the server uses.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.