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

# Finance District MCP Server

> The fastest way to give any AI agent a production-ready crypto wallet — plug in via MCP and go.

The Agent Wallet MCP server is the primary integration point for AI agents. It exposes wallet capabilities as tools that any MCP-compatible client can discover and use — Claude Code, Cursor, Windsurf, n8n, or your own custom agent.

The server is **remote and hosted** at `https://wallet-mcp.fd.xyz`. There's nothing to install, no local processes to run, and no infrastructure to manage.

## What is MCP?

[MCP (Model Context Protocol)](https://modelcontextprotocol.io/) is an open standard by Anthropic for connecting AI assistants to external tools and data sources. Think of it as a universal adapter — any MCP-compatible client can connect to any MCP server and discover what it can do.

Agent Wallet publishes wallet operations as MCP tools. When your AI agent connects, it automatically discovers all available capabilities and can use them through natural language.

## Connection Details

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

No API keys or bearer tokens to manage. When your MCP client connects for the first time, it triggers an OAuth authorization flow that opens a browser — sign in with your [District Pass](/overview/district-pass) (if you aren't already) and authorize the client to access your Finance District account.

## Connect

Add the MCP server to your client and authorize it through the District Pass OAuth flow. Setup instructions for Claude Code, Cursor, Windsurf, n8n, and custom clients are in [MCP Compatible Clients](/agent-wallet/ai-integration/mcp-clients).

## Verify the Connection

After configuring your client, verify the agent can reach the wallet:

> "What Finance District tools do you have?"

The agent should list the available wallet capabilities. Then try:

> "What's my wallet balance?"

If you see your balance (even if it's zero), the connection is working.

## Tools Reference

The Finance District Wallet MCP server exposes **16 tools** across three categories. MCP clients discover all tool parameters automatically; CLI users can run `fdx wallet <tool> --help`.

**Wallet Operations (12)**

1. `getWalletOverview` — balances across the Agent Wallet and Smart Accounts
2. `getAccountActivity` — transaction history for one account on one chain
3. `getTokenPrice` — USD price + 24h change for a token
4. `transferTokens` — transfer tokens across EVM, Solana, Bitcoin, and Sui
5. `swapTokens` — quote or execute a token swap (quote-only by default)
6. `discoverYieldStrategies` — discover DeFi yield strategies (**EVM chains only**)
7. `getYieldPositions` — list active yield positions for an account on a chain
8. `depositForYield` — deposit into a yield strategy
9. `withdrawFromYield` — withdraw from a yield position by vault token address
10. `getRedemptionRequests` — track async vault-withdrawal status (Pending / Finalized / Rejected)
11. `resolveNameService` — resolve ENS (.eth), SNS (.sol), Unstoppable Domains
12. `signMessage` — EIP-191 personal\_sign or EIP-712 typed-data signing (EVM)

**Payments (2)**

13. `authorizePayment` — build an x402 payment authorization from a 402 response
14. `getX402Content` — fetch from an x402 API and auto-pay on HTTP 402

**Support (2)**

15. `getMyInfo` — authenticated user profile + all wallet addresses (EVM, Solana, Bitcoin, Sui)
16. `reportIssue` — file a bug report (creates a GitHub issue)

<Note>
  **Sui: transfers only.** Swap, yield, signing, and Smart Account tools are not supported on Sui.
</Note>

***

## Authentication

Authentication uses **OAuth Authorization Code Flow with PKCE** — the same standard used by major web applications:

1. Your MCP client connects to `https://wallet-mcp.fd.xyz`
2. The server responds with an OAuth authorization URL
3. Your client opens a browser window
4. You sign in with your District Pass (if not already) and authorize the client to access your Finance District account
5. The OAuth flow completes and your client receives a token
6. Subsequent requests use this token automatically

**Token refresh** is handled automatically by the OAuth flow. You shouldn't need to re-authenticate unless you explicitly revoke access.

**Revoking access** — if you want to disconnect a specific MCP client, you can revoke its OAuth token through the Signer Service web interface.

**Client registration** — popular MCP clients (Claude Desktop, Cursor, Windsurf, Claude Code, n8n) are pre-registered and work out of the box. If you're building a custom MCP client, see [Client Registration](/agent-wallet/ai-integration/mcp-clients#client-registration) for supported registration methods.

## Error Handling

Common scenarios your agent may encounter:

| Error                   | Meaning                                              | Resolution                                                   |
| ----------------------- | ---------------------------------------------------- | ------------------------------------------------------------ |
| Authentication failed   | OAuth token expired or revoked                       | Re-authenticate through browser flow                         |
| Insufficient balance    | Wallet doesn't have enough tokens for the operation  | Fund the wallet with more tokens                             |
| Transaction failed      | On-chain error (gas, nonce, network issue)           | Retry — transient errors resolve on retry                    |
| Unsupported chain/token | Requested operation on an unsupported chain or token | Check [Supported Networks](/agent-wallet/supported-networks) |

All tool responses follow a consistent shape:

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
// Success
{ "success": true, "data": { ... } }

// Failure
{ "success": false, "error": { "code": "...", "message": "...", "retryable": true, "details": {} } }
```

If `retryable` is `true`, the client may retry the same request once. Otherwise, inputs or state must change before retrying.

MCP clients typically display tool errors in the conversation. The agent can often explain what went wrong and suggest a fix.