> ## 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.

# Quickstart: call your first Relay MCP tool

> Connect an MCP client to the Relay MCP server, complete the OAuth flow, and list transactions for one of your organizations.

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](https://mcp.docs.relayfi.com/connect-an-agent.md) 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:

```text theme={null}
https://mcp.relayfi.com/mcp
```

## 2. Let the client authorize

**1. Client sends an unauthenticated request**

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

**2. 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`.

**3. 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.

**4. 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.

> [!NOTE]
>
> 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](https://mcp.docs.relayfi.com/concepts/transport.md#common-tool-arguments).

```json Request theme={null}
{
  "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."
    }
  }
}
```

```json Response theme={null}
{
  "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.

```json Request theme={null}
{
  "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

> [card] [Connect an agent](https://mcp.docs.relayfi.com/connect-an-agent.md)
>
> Setup steps for Claude and ChatGPT.

> [card] [Authentication](https://mcp.docs.relayfi.com/concepts/authentication.md)
>
> Scopes, audience binding, and the discovery document.

> [card] [Tool reference](https://mcp.docs.relayfi.com/tools/list-organizations.md)
>
> Every tool's input and output schema.

> [card] [Errors](https://mcp.docs.relayfi.com/concepts/errors.md)
>
> Tool errors, `401`, and rate limits.


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