Skip to main content

Overview

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.

Installation

npm install @atxp/client

Client

atxpClient

atxpClient({
  mcpServer: string,
  account: Account,
  oauthDatabase?: SQLiteOAuthDatabase | RedisOAuthDatabase,
  onAuthorize?: (authorizationData: AuthorizationData) => Promise<void>,
  onAuthorizeFailure?: (error: AuthorizationError) => Promise<void>,
  onPayment?: (paymentData: PaymentData) => Promise<void>,
  onPaymentFailure?: (error: PaymentError) => Promise<void>,
  approvePayment?: (request: PaymentRequest) => Promise<boolean>
}): Promise<Client>
Creates an ATXP client that can be used to interact with ATXP-enabled MCP servers. Arguments
args
ClientArgs
required
Configuration arguments for the client. See ClientArgs for detailed property information.
Return
client
Promise<Client>
Returns an object that can be used to call tools on the MCP server, handling authorization and payment.
Callbacks The ATXP client provides a callback system to handle authorization and payment events throughout the application lifecycle:
The authorization callbacks handle the OAuth flow:
  1. onAuthorize - Called when a user successfully completes OAuth authorization
  2. 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.
The payment callbacks handle the payment processing flow:
  1. onPayment - Called when a payment is successfully processed
  2. 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
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://browse.mcp.atxp.ai/',
  account: new Account(atxpConnectionString),
})

callTool

callTool({
  name: string,
  arguments: any
}): Promise<ToolResult>
Calls a tool on the configured MCP server.
A list of ATXP-provided MCP servers can be found here.
Arguments Return Returns 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_STRING

const client = await atxpClient({
  mcpServer: 'https://browse.mcp.atxp.ai/',
  account: new Account(atxpConnectionString),
})

const prompt = "What are the top 3 articles by points on https://news.ycombinator.com?";

const result = await client.callTool({
  name: 'browse_run_task',
  arguments: { instructions: prompt }
});

ATXPAccount

ATXPAccount

ATXPAccount(
  connectionString: string,
  opts?: {
    fetchFn?: FetchLike,
    network?: Network
  }): ATXPAccount
Creates an ATXP account object that can be used to create an ATXP client. Arguments

Account Types Moved to Separate Packages

v0.9.0+ Breaking Change: Blockchain-specific account types have been moved to dedicated packages as part of the modular architecture.
  • BaseAccount → Moved to @atxp/base
  • 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.