@atxp/client - ATXP Docs

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.

Show ClientArgs properties

mcpServer

string

required

The URL of the MCP server to connect to.

account

Account

required

The account to use for authentication. See Account for more details.

oauthDatabase

SQLiteOAuthDatabase | RedisOAuthDatabase

The OAuth database to use for storing tokens; either a SQLiteOAuthDatabase or RedisOAuthDatabase. If not provided, the tokens will be stored in memory.

onAuthorize

function

Callback function called when a user successfully authorizes the application. This is triggered after OAuth authorization completes successfully.

onAuthorize: async (authorizationData: AuthorizationData) => {
  console.log('User authorized:', authorizationData.userId);
  // Handle successful authorization
}

See AuthorizationData for callback parameter details.

onAuthorizeFailure

function

Callback function called when authorization fails or is denied by the user.

onAuthorizeFailure: async (error: AuthorizationError) => {
  console.error('Authorization failed:', error.message);
  // Handle authorization failure
}

See AuthorizationError for error details.

onPayment

function

Callback function called when a payment is successfully processed.

onPayment: async (paymentData: PaymentData) => {
  console.log('Payment successful:', paymentData.amount, paymentData.currency);
  // Handle successful payment
}

See PaymentData for callback parameter details.

onPaymentFailure

function

Callback function called when a payment fails or is rejected.

onPaymentFailure: async (error: PaymentError) => {
  console.error('Payment failed:', error.message);
  // Handle payment failure
}

See PaymentError for error details.

approvePayment

function

Custom payment approval logic. If not provided, all payments are automatically approved.

approvePayment: async (request: PaymentRequest) => {
  // Custom business logic for payment approval
  if (request.amount <= 100) {
    return true; // Auto-approve payments under $100
  }
  return await confirmLargePayment(request);
}

See PaymentRequest for request details.

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:

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://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

Show callTool arguments

name

string

required

The name of the tool to call.

arguments

any

required

The arguments to pass to the tool.

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(
  connectionString: string,
  opts?: {
    fetchFn?: FetchLike,
    network?: Network
  }): ATXPAccount

Creates an ATXP account object that can be used to create an ATXP client. Arguments

Show ATXPAccount arguments

connectionString

string

required

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

opts

object

The options for the ATXP account.

Show ATXPAccount opts properties

fetchFn

FetchLike

The fetch function to use for the ATXP account.

network

Network

The network to use for the ATXP account.

BaseAccount

BaseAccount(
  baseRPCUrl: string,
  sourceSecretKey: string
): BaseAccount

Creates a Base account object that can be used to create a Base client. The baseRPCUrl is the Base RPC URL and the sourceSecretKey is the source secret key for the Base account. You can find your source secret key in your Base account dashboard at https://base.org/. Arguments

Show BaseAccount arguments

baseRPCUrl

string

required

The Base RPC URL.

sourceSecretKey

string

required

The source secret key for the Base account.

API documentation

​Overview

​Installation

​Client

​atxpClient

​callTool

​ATXPAccount

​ATXPAccount

​BaseAccount

​BaseAccount

Overview

Installation

Client

atxpClient

callTool

ATXPAccount

ATXPAccount

BaseAccount

BaseAccount