The @atxp/client package is used to create MCP clients with OAuth authentication and payment processing via ATXP.
This package depends on types and utilities from @atxp/common. All shared types like Account, ClientArgs, AuthorizationData, PaymentData, and error types are documented in the common package.
The OAuth database to use for storing tokens; either a SQLiteOAuthDatabase or RedisOAuthDatabase. If not provided, the tokens will be stored in memory.
Returns an object that can be used to call tools on the MCP server, handling authorization and payment.
CallbacksThe ATXP client provides a callback system to handle authorization and payment events throughout the application lifecycle:
Authorization flow
The authorization callbacks handle the OAuth flow:
onAuthorize - Called when a user successfully completes OAuth authorization
onAuthorizeFailure - Called when authorization fails or is denied
Use onAuthorize to store user session data, update UI state, or initialize user-specific resources. Use onAuthorizeFailure to show appropriate error messages and provide retry options.
Payment flow
The payment callbacks handle the payment processing flow:
onPayment - Called when a payment is successfully processed
onPaymentFailure - Called when a payment fails or is rejected
Callback functions should not throw unhandled exceptions as they may interrupt the payment flow. Always wrap callback logic in try-catch blocks when necessary.
Example usage
Without callbacks
With callbacks
An example showing how to use the ATXP client without callbacks, passing in only the required arguments.
import { atxpClient } from '@atxp/sdk'import { Account } from '@atxp/common'const client = await atxpClient({ mcpServer: 'https://search.mcp.atxp.ai/', account: new Account(atxpConnectionString),})
A complete example showing how to use the available callbacks for handling authorization and payment events:
import { atxpClient } from '@atxp/sdk'import { Account } from '@atxp/common'// Read the ATXP connection string from the environment variables// Your connection string should look like https://accounts.atxp.ai?connection_token=<random_string>// and can be found in your ATXP account dashboard at https://accounts.atxp.ai/const atxpConnectionString = process.env.ATXP_CONNECTION_STRINGconst client = await atxpClient({ mcpServer: 'https://search.mcp.atxp.ai/', account: new Account(atxpConnectionString), // Authorization callbacks onAuthorize: async (authorizationData) => { console.log('User successfully authorized:', authorizationData.userId); // You might want to store user session data or update UI }, onAuthorizeFailure: async (error) => { console.error('Authorization failed:', error.message); // Handle failed authorization - show error message to user }, // Payment callbacks onPayment: async (paymentData) => { console.log(`Payment of ${paymentData.amount} ${paymentData.currency} successful`); // Update user's account balance, send confirmation email, etc. }, onPaymentFailure: async (error) => { console.error('Payment failed:', error.message); // Handle payment failure - show error, retry logic, etc. }, // Payment approval logic approvePayment: async (paymentRequest) => { // Custom business logic for payment approval if (paymentRequest.amount <= 100) { return true; // Auto-approve payments under $100 } // For larger payments, you might want to require additional confirmation return await confirmLargePayment(paymentRequest); }});
ReturnReturns a Promise<ToolResult> typed object that contains the result of the tool call.Example usage
import { atxpClient } from '@atxp/sdk'import { Account } from '@atxp/common'// Read the ATXP connection string from the environment variables// Your connection string should look like https://accounts.atxp.ai?connection_token=<random_string>// and can be found in your ATXP account dashboard at https://accounts.atxp.ai/const atxpConnectionString = process.env.ATXP_CONNECTION_STRINGconst client = await atxpClient({ mcpServer: 'https://search.mcp.atxp.ai/', account: new Account(atxpConnectionString),})const query = "latest news on the US financial sector";const result = await client.callTool({ name: 'search_search', arguments: { query }});
The ATXP connection string in the format: https://accounts.atxp.ai?connection_token=<token>. This connection string identifies the ATXP account that will be used by the client to pay for MCP server tool calls. You can find your connection string in your ATXP account dashboard at https://accounts.atxp.ai/.
SolanaAccount → Moved to @atxp/solana (install with npm install @atxp/solana)
The core @atxp/client package now focuses on essential features with zero blockchain code (except ATXPLocalAccount), resulting in reduced bundle sizes and eliminated security vulnerabilities for users who don’t need blockchain-specific functionality.
