Pear MCP integration guide

Use this guide to build an MCP client or a server-side integration for Pear. If you only want to connect an existing MCP client, read the Orchard MCP user guide.

Integration flow

A complete trading flow has eight steps:

1. Connect to the Pear MCP endpoint.
2. Authenticate the user with OAuth 2.0 or an API key.
3. Call list_trade_accounts and select a trade account.
4. Call sync_account before you read positions.
5. Call read tools to find assets and review account data.
6. Call a plan_* tool and show the plan to the user.
7. After user approval, call the matching execute_* tool.
8. Sync the account and check the execution result.

A read-only integration uses steps 1 through 5. It does not need the write scope.

Choose an authentication method

Pear supports two authentication methods.

Use OAuth 2.0 for a user-facing client. Do not put an API key in browser code.

Authentication does not connect an exchange account. Users connect and manage trade accounts in the Pear application. Never ask a user to send exchange credentials through an MCP tool.

Service contract

Connect and authenticate

OAuth 2.0 flow

The Pear authorization server uses the authorization code flow with PKCE S256. It supports dynamic client registration and refresh tokens. The client is public. Set token_endpoint_auth_method to none.

Use this flow:

1. Send an unauthenticated request to the MCP endpoint.
2. Read the WWW-Authenticate response header.
3. Get the RFC 9728 metadata URL from resource_metadata.
4. Get the protected-resource metadata from that URL.
5. Get the authorization server URL from authorization_servers[0].
6. Get the authorization server metadata.
7. Register the application at the listed registration_endpoint when you do not have a client registration.
8. Redirect the user to the listed authorization_endpoint.
9. Send an authorization code request with PKCE S256.
10. Let the Pear page handle sign-in and consent.
11. Exchange the authorization code at the listed token_endpoint.
12. Send the access token in the Authorization: Bearer <access-token> header.
13. Use the refresh token when the access token expires.

Store state and the PKCE verifier in one short-lived authorization transaction. Compare the returned state with the stored value. Stop the flow when the values do not match.

Request only the scopes that the application needs.

Register an OAuth client

Send this request to the registration endpoint:

POST <registration_endpoint>
Content-Type: application/json

{
  "redirect_uris": ["https://client.example.com/oauth/callback"],
  "token_endpoint_auth_method": "none",
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "client_name": "Example MCP Client"
}

The redirect URI must use HTTPS. Pear also accepts an HTTP redirect URI for localhost, 127.0.0.1, or ::1.

Request an authorization code

Send these parameters to the authorization endpoint:

response_type=code
client_id=<oauth-client-id>
redirect_uri=<registered-redirect-uri>
scope=mcp:read mcp:write
state=<random-state>
code_challenge=<base64url-sha256-verifier>
code_challenge_method=S256

Exchange the authorization code

Send the returned code as form data:

POST <token_endpoint>
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&client_id=<oauth-client-id>&redirect_uri=<registered-redirect-uri>&code=<authorization-code>&code_verifier=<pkce-verifier>

The OAuth client_id identifies the OAuth application. It does not identify the integration for volume attribution.

API key flow

Send the API key in the x-api-key header on each MCP request.

API keys have these scopes:

You cannot create or revoke an API key through MCP. A signed-in user can create a key in the Pear application. The user can also call POST /api-keys on the Pear gateway.

POST https://pro-gateway.pearprotocol.io/api-keys
Authorization: Bearer <first-party-session-token>
Content-Type: application/json

{
  "label": "Example MCP integration",
  "scope": "read_write",
  "expiresAt": "2027-01-01T00:00:00Z"
}

expiresAt is optional. The response returns the raw key one time. Store the key in a secret manager.

Use GET /api-keys to list keys. Use DELETE /api-keys/:id to revoke a key.

The MCP validates a key through GET /auth/api-key/me. An unknown, expired, or revoked key gets HTTP 401.

An API key has priority when a request has both credential headers. An invalid API key does not fall back to the bearer token.

Send an MCP request

Use an MCP SDK in production. This raw request shows API-key authentication and optional volume attribution:

curl https://mcp.pearprotocol.io/mcp \
  --request POST \
  --header 'content-type: application/json' \
  --header 'accept: application/json, text/event-stream' \
  --header 'x-api-key: <api-key>' \
  --header 'x-client-id: <client-code>' \
  --data '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

For OAuth, replace x-api-key with Authorization: Bearer <access-token>.

Add volume attribution

Add a Pear-issued code to each MCP request that needs volume attribution:

x-api-key: <api-key>
x-client-id: <client-code>

The value must be an active client_ids.code that Pear assigned. The value is not any of these identifiers:

• OAuth client_id
• API key UUID
• Raw API key
• User UUID
• Trade account UUID

Pear records the code on supported executions and fills. Pear can then group trading volume by integration.

x-client-id is an attribution label. It is not an authentication credential. Pear checks that the code exists and is active. Pear does not bind the code to an API key or OAuth client.

Send x-client-id on every request that needs attribution. The value does not continue to the next request.

When you omit x-client-id, the trade has no integration attribution unless the service has a default code. An unknown or inactive code causes the related write to fail.

Attribution covers market trades, TWAP schedules, conditional triggers, and manual rebalances. Ladder creation and automatic rebalance settings do not automatically receive the default attribution code.

These fields have separate purposes:

Build the account flow

A trade account is a connected exchange account. It tells Pear which exchange, wallet, or subaccount a tool must use.

Users manage trade accounts in the Pear application. MCP does not create, change, delete, restore, or return credentials for a trade account.

Select an account

Call list_trade_accounts when the client does not have a current account. This tool does not need a tradeAccountId.

Use this selection flow:

1. Call list_trade_accounts.
2. If the list is empty, tell the user to connect an account in Pear.
3. If the list has one active account, omit tradeAccountId. MCP selects that account.
4. If the list has multiple active accounts, show an account picker.
5. Pass the selected account id as tradeAccountId.
6. Keep the selection for the current task.
7. Pass the same ID to later account-scoped calls.

Use the same tradeAccountId for both parts of a plan_* and execute_* flow. A plan token belongs to one user and one trade account.

Use Alias, Connector as the account label. For example, use Main, Hyperliquid. Show a short exchangeIdentifier only when two accounts have the same label.

The tool can return these account errors:

Do not show the raw error as the only response. Tell the user what action to take.

All order tools are account-scoped. Position, balance, execution, TCA, pending-order, rebalance, saved-basket, cancellation, management, and synchronization tools are also account-scoped.

Market discovery, basket discovery, prediction-market search, notifications, and list_trade_accounts do not need an account selection.

Account fields

Each account from list_trade_accounts has these fields:

list_trade_accounts accepts includeDeleted. Keep this value false during normal use. An account-scoped tool cannot use a deleted account.

Sync the account

Call sync_account after the user connects an account. Call it before the first position read. Call it again after an order settles.

The tool imports exchange positions and fills into Pear. It does not place an order.

Build the trade flow

Every action that places an order uses a plan tool and an execute tool.

1. Call the matching plan_* tool.
2. Keep the returned single-use planToken.
3. Show the complete plan to the user.
4. Wait for user approval.
5. Call the matching execute_* tool.
6. Send the token and the required routing field.
7. Check the execution result.
8. Call sync_account after the order settles.

A plan validates and sizes the action. It does not place an order.

An execute_* tool does not accept the original planning fields. It uses the stored plan. The token belongs to one user, trade account, tool family, and routing mode.

Handle an unclear execution result

Do not create a new plan after an unclear execution result. First call these tools:

1. Call sync_account.
2. Call get_position.
3. Call get_execution when you have an execution ID.

Use this recovery flow for binding_mismatch, execution_in_progress, and unknown or expired token responses. These responses do not prove that Pear did not place an order.

Handle schemas and responses

Use MCP tools/list as the source for each input schema. The server validates arguments before it calls the execution engine.

Interactive hosts can show widgets for markets, positions, orders, baskets, notifications, plans, and execution receipts. Other hosts receive structured JSON or JSON text.

The server rejects a plain JSON-text response above an estimated 25,000 tokens. This limit does not apply to widget-backed structured responses. Use filters, limit, cursor, or offset to request less data.

Tool reference

The current manifest contains 29 tools. It has 13 read tools and 16 write tools.

Read tools

These tools require mcp:read.

Order plan and execute tools

These tools require mcp:write.

Other write tools

These tools require mcp:write.

MCP resources

The mcp:read scope exposes pear://asset-filters. This resource returns the connectors, asset classes, and categories that discover_assets accepts.

MCP Apps hosts can also read hash-pinned ui:// resources for the registered widgets. These resources show tool results. They do not change authentication or tool behavior.

Errors and security

The MCP validates bearer JWTs locally. It does not check OAuth grant revocation on every request. The Pear gateway checks revocation for engine-backed calls. A revoked token can reach cache-only reads until the JWT expires.

API keys never appear in tool arguments or tool results. MCP does not expose exchange credentials or trade-account changes as tools.

Plan tokens are single-use and expire. Redis stores token state and the replay result.

Each MCP request receives only the tools that its verified scopes allow.

Integration checklist

Before release, verify these items:

• Use OAuth 2.0 with PKCE S256 for a user-facing client.
• Use a read_write API key only when the integration needs write tools.
• Keep API keys out of source control and browser storage.
• Send x-client-id on each request that needs volume attribution.
• Confirm that Pear activated the client_ids.code.
• Call list_trade_accounts before the first account-scoped tool.
• Call sync_account before position reads and after settled executions.
• Show each plan_* result before you call the matching execute_* tool.
• Page large read results.
• Handle HTTP 401, HTTP 429, tool errors, and unclear execution results.