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

# Authentication: OAuth 2.1 with audience-bound tokens

> Relay MCP is an OAuth 2.1 protected resource. Every request must carry a Bearer token in the Authorization header. Tokens must be audience-bound via RFC 8707.

Relay MCP is an OAuth 2.1 protected resource that fails closed. Every request must include a valid `Authorization: Bearer <token>` header. Tokens sent in query parameters or tool arguments are ignored and the request is rejected. The server never falls back to an unauthenticated state.

## Discovery endpoint

Before acquiring a token, query the protected resource metadata to find the authorization server and supported scopes.

```bash theme={null}
GET https://mcp.relayfi.com/.well-known/oauth-protected-resource/mcp
```

```json Response theme={null}
{
  "resource": "https://mcp.relayfi.com/mcp",
  "authorization_servers": ["https://app.relayfi.com/oauth"],
  "scopes_supported": [
    "organizations.read",
    "accounts.read",
    "transactions.read",
    "cards.read",
    "statements.read",
    "contacts.read",
    "catalog-items.read",
    "invoices.read"
  ],
  "bearer_methods_supported": ["header"]
}
```

## Token requirements

* **Header only**: pass the token in the `Authorization` header. Never in a query parameter or tool argument.
* **Audience-bound**: tokens must be minted for the MCP endpoint via the RFC 8707 `resource` parameter. Tokens created for a different audience are rejected.
* **Scope and organization bound**: the token carries a fixed set of scopes and a fixed list of organizations. A tool call succeeds only when the token includes the required scope and the requested `organizationId` is in the token's organization list.

## Scopes and tool access

| Scope | Tools unlocked |
| - | - |
| `organizations.read` | `list_organizations` |
| `accounts.read` | `list_accounts`, `get_account` |
| `transactions.read` | `list_transactions`, `get_transaction` |
| `cards.read` | `list_cards`, `get_card` |
| `statements.read` | `list_bank_statements`, `download_bank_statement` |
| `contacts.read` | `list_contacts`, `get_contact` |
| `catalog-items.read` | `list_catalog_items`, `get_catalog_item` |
| `invoices.read` | `list_invoices`, `get_invoice`, `list_tax_rates`, `list_discounts` |

`tools/list` returns only the tools unlocked by the scopes on your token. Request only the scopes your agent needs.

## Authentication failure

When the token is missing, malformed, or unverifiable, the server returns HTTP `401 Unauthorized` with this header:

```text theme={null}
WWW-Authenticate: Bearer realm="mcp", error="invalid_token", resource_metadata="https://mcp.relayfi.com/.well-known/oauth-protected-resource/mcp"
```

This is a transport-level failure, not a tool error. Your client must re-authorize before retrying the request.

## Authentication flow

**1. Discover the authorization server**

Call `GET /.well-known/oauth-protected-resource/mcp` to read the `authorization_servers` array and `scopes_supported`.

**2. Request a token**

Complete OAuth against the advertised authorization server. Include the `resource` parameter set to the MCP endpoint so the token is audience-bound.

**3. Send the token on every request**

Include `Authorization: Bearer <token>` in the header of every `POST /mcp` call. The server is stateless and does not remember prior authorization.

**4. Handle 401 by re-authorizing**

If you receive a `401`, re-read the discovery document and repeat the OAuth flow. Do not retry the same request with the same token.

> [card] [Transport](https://mcp.docs.relayfi.com/concepts/transport.md)
>
> Learn how Relay MCP uses a single POST endpoint with JSON responses.

> [card] [Errors](https://mcp.docs.relayfi.com/concepts/errors.md)
>
> Understand how auth failures and rate limits surface at the transport level.


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