Quickstart: call your first Relay MCP tool

This quickstart walks through connecting an MCP client to the Relay MCP server, letting it complete the OAuth 2.1 flow, and making your first tool call. You will list your organizations, then fetch a page of recent transactions.

Prerequisites

Claude or ChatGPT. These are the only supported MCP clients. See Connect an agent for setup.
Access to a Relay organization whose token can be issued for the MCP resource.

1. Add the server

Add the Relay MCP endpoint to your MCP client as a remote Streamable HTTP server:

https://mcp.relayfi.com/mcp

2. Let the client authorize

Client sends an unauthenticated request

The MCP client POSTs to /mcp without a bearer token. The server replies with 401 and a WWW-Authenticate header pointing at the protected-resource metadata.

Client reads the discovery document

The client fetches GET /.well-known/oauth-protected-resource/mcp (RFC 9728) to find the authorization server, supported scopes, and required bearer_methods_supported.

Client completes the OAuth flow

The client authorizes against the advertised authorization server and requests a token whose RFC 8707 resource parameter is the MCP endpoint URL. Tokens minted for a different audience are rejected.

Client retries with the token

The client retries the original request with Authorization: Bearer <access_token>. The server verifies scopes and organization membership on every tool call.

Bearer tokens are accepted in the header only. Never place a token in a query parameter or in tool arguments.

3. List your organizations

Once the client is authorized, call list_organizations to resolve an organizationId. Every tool call must include an intent argument: a short, factual description of what the user asked for and why this call serves it. See Common tool arguments.

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_organizations",
    "arguments": {
      "intent": "User asked for their settled transactions since July 1; resolving which organization to query."
    }
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "data": [
        { "object": "organization", "id": "org_1", "name": "Acme Inc" }
      ]
    }
  }
}

If exactly one organization is returned, the agent may proceed with it. If several are returned and the intent is ambiguous, the agent should ask the user which one to use.

4. List transactions

Use the resolved organizationId to fetch a page of transactions.

Request

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "list_transactions",
    "arguments": {
      "intent": "User asked for their settled transactions since July 1.",
      "organizationId": "org_1",
      "status": "settled",
      "occurredAfter": "2026-07-01",
      "pageSize": 25
    }
  }
}

The response contains up to 25 transactions plus a pagination object. If hasNextPage is true, pass the returned nextCursor back on the next call with the same filters and pageSize.

Next steps

Connect an agent

Setup steps for Claude and ChatGPT.

Authentication

Scopes, audience binding, and the discovery document.

Tool reference

Every tool’s input and output schema.

Errors

Tool errors, 401, and rate limits.

Get Started

Concepts

Quickstart: call your first Relay MCP tool

Prerequisites

1. Add the server

2. Let the client authorize

3. List your organizations

4. List transactions

Next steps

Connect an agent

Authentication

Tool reference

Errors

​Prerequisites

​1. Add the server

​2. Let the client authorize

​3. List your organizations

​4. List transactions

​Next steps

Connect an agent

Authentication

Tool reference

Errors

Prerequisites

1. Add the server

2. Let the client authorize

3. List your organizations

4. List transactions

Next steps