Authentication: OAuth 2.1 with audience-bound tokens

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.

GET https://mcp.relayfi.com/.well-known/oauth-protected-resource/mcp

Response

{
  "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:

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

Discover the authorization server

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

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.

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.

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.

Transport

Learn how Relay MCP uses a single POST endpoint with JSON responses.

Errors

Understand how auth failures and rate limits surface at the transport level.

Get Started

Concepts

Authentication: OAuth 2.1 with audience-bound tokens

Discovery endpoint

Token requirements

Scopes and tool access

Authentication failure

Authentication flow

Transport

Errors

​Discovery endpoint

​Token requirements

​Scopes and tool access

​Authentication failure

​Authentication flow

Transport

Errors

Discovery endpoint

Token requirements

Scopes and tool access

Authentication failure

Authentication flow