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

# MCP server

> Connect an AI assistant to your Orchestrate project.

Orchestrate exposes a [Model Context Protocol](https://modelcontextprotocol.io) server, so an AI
assistant — Claude, ChatGPT, Cursor, or anything else that speaks MCP — can read your
project's payments and payouts and answer questions about them in place.

It is the same data as the API, reached through a different door. Access is scoped to one
project, and every tool but one is read-only.

```
https://mcp.orqex.com/public
```

## What you can do with it

Ask the questions you would otherwise write a script for:

* *Why did payment `pi_...` fail?* — the assistant reads the intent, its attempts and the
  failure reason.
* *Show me everything this customer has paid this month.*
* *What does the provider actually have on file for this payment?* — via `inspect_payment`.
* *This payment is stuck. Recover it.* — via `requery_payment`, the one tool that writes.

## Connecting

Most MCP clients only need the URL. Point your client at the server and it will run the
OAuth flow itself: it registers, opens a browser, and you approve the connection from your
Orchestrate dashboard.

```json theme={null}
{
  "mcpServers": {
    "orqex": {
      "url": "https://mcp.orqex.com/public"
    }
  }
}
```

Approval happens in your dashboard, on the project you are granting access to. Once you
approve, the client receives a token and the connection is live.

<Warning>
  Approving a connection gives that client read access to your project's payment data, and
  the ability to requery a failed payment. Only approve clients you control.
</Warning>

## Authentication

The server implements OAuth 2.1 with PKCE and dynamic client registration, so a compliant
client needs no manual setup.

| Endpoint                      |                                                                    |
| ----------------------------- | ------------------------------------------------------------------ |
| Protected resource metadata   | `GET https://mcp.orqex.com/.well-known/oauth-protected-resource`   |
| Authorization server metadata | `GET https://mcp.orqex.com/.well-known/oauth-authorization-server` |
| Client registration           | `POST https://mcp.orqex.com/public/oauth/register`                 |
| Authorization                 | `GET https://mcp.orqex.com/public/oauth/authorize`                 |
| Token                         | `POST https://mcp.orqex.com/public/oauth/token`                    |

The scope is `project:mcp`. The token you receive is a project secret key, sent as a bearer
token on every subsequent request.

<Note>
  Tokens issued through the OAuth flow are **live-environment** keys. If you want an
  assistant to see sandbox data instead, skip OAuth and connect with a sandbox secret key
  directly (see below).
</Note>

### Connecting with a key you already have

If your client supports a static bearer token, any active secret key works — including a
`sk_sandbox_` one:

```json theme={null}
{
  "mcpServers": {
    "orqex": {
      "url": "https://mcp.orqex.com/public",
      "headers": {
        "Authorization": "Bearer sk_sandbox_..."
      }
    }
  }
}
```

The key decides the project and the environment, exactly as it does on the API. IP
allowlists on the key apply here too.

## Revoking access

Revoke the key in your [dashboard](https://app.orqex.com). The client loses access
immediately; reconnecting means going through approval again.

## Limits

60 requests per minute per key, and 10 per minute for unauthenticated requests. Lists are
cursor-paginated, 20 results per page by default and 100 at most.

<Card title="Available tools" icon="wrench" href="/mcp/tools">
  The full list of what an assistant can do.
</Card>