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

# MCP Server

> Manage your Prism integration from any AI agent — 18 tools for payments, wallets, Project Identify Tokens, staff, and more.

The Prism MCP Server exposes your payment platform as tools that any MCP-compatible AI agent can discover and use. It targets providers managing their Prism integration programmatically — querying payments, configuring Projects, managing wallets, and monitoring earnings — all from within an AI assistant.

| Property       | Value                                   |
| -------------- | --------------------------------------- |
| Server URL     | `https://prism-mcp.fd.xyz`              |
| Transport      | Streamable HTTP                         |
| Authentication | OAuth Authorization Code Flow with PKCE |

## Account Model

Each authenticated caller is a **Provider** (tenant) identified by their account. Providers own one or more **Projects** — the core unit representing a payment integration. Most tools operate within a Project context.

* If `projectId` is omitted, tools automatically default to the provider's first active Project.
* IDs are GUIDs throughout (e.g., `projectId`, `walletId`, `paymentId`, `projectIdentifyTokenId`).

## Connection Setup

Add the Prism MCP server to your MCP client using the server URL above. Authentication uses OAuth Authorization Code Flow — the first connection opens a browser for you to sign in with your [District Pass](/overview/district-pass).

<Tabs>
  <Tab title="Claude Desktop">
    Add to your `claude_desktop_config.json`:

    ```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
    {
      "mcpServers": {
        "prism": {
          "type": "http",
          "url": "https://prism-mcp.fd.xyz"
        }
      }
    }
    ```
  </Tab>

  <Tab title="Cursor / Windsurf">
    Add the server URL `https://prism-mcp.fd.xyz` in your editor's MCP settings panel. The OAuth flow triggers automatically on first use.
  </Tab>

  <Tab title="Custom Agent">
    Connect using any MCP client library. The server implements standard Streamable HTTP transport with OAuth 2.0 PKCE authentication.

    ```
    MCP Server: https://prism-mcp.fd.xyz
    Transport: Streamable HTTP
    Auth: OAuth 2.0 Authorization Code + PKCE
    ```
  </Tab>
</Tabs>

After connecting, verify the integration:

> "What Prism tools do you have available?"

The agent should list all 18 tools. Then try:

> "Show me my Projects."

## Tool Reference

All tools return JSON. Errors use `{ "error": "CODE", "message": "description" }`.

<Tip>
  **MCP clients** discover all tool parameters automatically on connection. **CLI users** can run `fdx prism <tool> --help` to see full parameter details. No need to memorize — the tooling tells you what it needs.
</Tip>

### Provider

| Tool                | Description                                                             |
| ------------------- | ----------------------------------------------------------------------- |
| `getProviderInfo`   | Get provider profile, available blockchain chains, and supported tokens |
| `updateAccountType` | Set the provider account type to `Personal` or `Business`               |

### Projects

A Project is the top-level entity representing one payment integration. Most tools operate within a Project context — if `projectId` is omitted, your default active Project is used.

| Tool                | Description                                                                           |
| ------------------- | ------------------------------------------------------------------------------------- |
| `listProjects`      | List all Projects owned by the authenticated provider                                 |
| `getProjectDetails` | Get full details for a Project including configuration, assets, networks, and wallets |
| `createProject`     | Create a new Project with name and accepted assets/networks configuration             |
| `updateProject`     | Update, activate, or deactivate a Project                                             |
| `configureProject`  | Read or update assets, networks, or wallets configuration for a Project               |

### Wallets

Manage on-chain wallet addresses registered to a Project for receiving settlement funds.

| Tool           | Description                                      |
| -------------- | ------------------------------------------------ |
| `listWallets`  | List all wallets registered for a Project        |
| `manageWallet` | Create, update, or delete a wallet for a Project |

### Project Identify Tokens

Manage Project Identify Tokens that authenticate your application against the Prism Gateway.

| Tool                         | Description                                                                           |
| ---------------------------- | ------------------------------------------------------------------------------------- |
| `listProjectIdentifyTokens`  | List Project Identify Tokens for a Project (secret values are never returned)         |
| `manageProjectIdentifyToken` | Create, disable, or delete a Project Identify Token. Secret returned only on creation |

### Staff

Manage staff access to Projects. Staff members are invited by email and must accept via a browser OAuth flow. Only the tenant owner can manage staff.

| Tool                    | Description                                                                                          |
| ----------------------- | ---------------------------------------------------------------------------------------------------- |
| `listStaff`             | List staff members for the provider, optionally scoped to a Project, with FIQL filtering and sorting |
| `manageStaff`           | Invite a staff member to a Project by email, or revoke an existing staff member's access             |
| `resendStaffInvitation` | Regenerate and resend an invitation email for a Pending staff member                                 |

### Payments

| Tool                | Description                                                                   |
| ------------------- | ----------------------------------------------------------------------------- |
| `listPayments`      | List payments with blockchain transaction details, asset info, and status     |
| `getPaymentDetails` | Get full details for a single payment including settlement breakdown and fees |

### Dashboard

| Tool                | Description                                                               |
| ------------------- | ------------------------------------------------------------------------- |
| `getEarnings`       | Earnings summary (total gross earnings) for a Project within a time range |
| `getRecentPayments` | Recent payment summaries for dashboard views                              |

## Example Interactions

Once connected, you can ask your AI agent questions like:

```
"List my active Projects."
"Show me all payments from the last 30 days."
"What are my total earnings this month?"
"Create a new identify token named 'production-v2' for my default Project."
"Add a USDC wallet on Base (chain ID 8453) with address 0xABC... to my Project."
"Disable Project Identify Token <id>."
"Get the full details for payment <id>."
```

## Error Handling

All tools return structured errors:

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{ "error": "ERROR_CODE", "message": "Human-readable description" }
```

Common errors:

| Error Code                          | Meaning                                                                |
| ----------------------------------- | ---------------------------------------------------------------------- |
| `MISSING_PROJECT_ID`                | `projectId` required but omitted (e.g., for activate action)           |
| `INVALID_PAYMENT_ID`                | `paymentId` is not a valid GUID                                        |
| `MISSING_NAME`                      | Name parameter required but not provided                               |
| `INVALID_ACTION`                    | Unknown action value passed to an action-discriminated tool            |
| `INVALID_ACCOUNT_TYPE`              | Account type must be `Personal` or `Business`                          |
| `MISSING_WALLET_ID`                 | `walletId` required but not provided or not a valid GUID               |
| `MISSING_PROJECT_IDENTIFY_TOKEN_ID` | `projectIdentifyTokenId` required but not provided or not a valid GUID |