@atxp/server

Overview

The @atxp/server package is a support package used for packages like @atxp/express. You should generally not need to reference @atxp/server directly.

This package depends on types and utilities from @atxp/common. All shared types like ATXPArgs and payment utilities are documented in the common package.

Installation

npm install @atxp/server

Functions

atxpAccountId

atxpAccountId(): string | null

Returns the accountId of the ATXP user of the current server request. Use this in the code of an MCP tool, or anywhere else inside the context of ATXP middleware, to get the current user.

Account ids should be treated as opaque strings. They are unique per user, but you should not assume they have any semantic meaning.

Arguments None Example usage

import { requirePayment, atxpAccountId } from '@atxp/server'
import BigNumber from 'bignumber.js'

server.tool(
  "add",
  "Use this tool to return a personalized greeting.",
  {
    name: z.string().describe("Name of the user"),
  },
  async ({ name }) => {
    // Require payment for the tool call
    await requirePayment({price: BigNumber(0.01)});
    const accountId = atxpAccountId();
    return {
      content: [
        {
          type: "text",
          text: `Hello ${name}! Your user id is ${accountId}`
        },
      ],
    };
  }
);

requirePayment

requirePayment({
  price: BigNumber,
  getExistingPaymentId?: () => Promise<string | null>
  }): Promise<void>

Requires payment before executing a tool. This function must be called before any paid tool logic.

The requirePayment function uses BigNumber for precise decimal arithmetic. Install it with npm install bignumber.js and import it as shown above.

Arguments

Show requirePayment arguments

price

BigNumber

required

The price to charge in USDC. See BigNumber for BigNumber usage details.

getExistingPaymentId

function

A function that returns the ID of an existing payment for the tool call. If not provided, a new payment will be created.

Example usage

import { requirePayment } from '@atxp/server'
import BigNumber from 'bignumber.js'

server.tool(
  "add",
  "Use this tool to add two numbers together.",
  {
    a: z.number().describe("The first number to add"),
    b: z.number().describe("The second number to add"),
  },
  async ({ a, b }) => {
    // Require payment for the tool call
    await requirePayment({price: BigNumber(0.01)});
    return {
      content: [
        {
          type: "text",
          text: `${a + b}`,
        },
      ],
    };
  }
);

Overview

Build Agents

Monetize MCP Tools

Developer Tools

API Reference

Overview

Installation

Functions

atxpAccountId

requirePayment

​Overview

​Installation

​Functions

​atxpAccountId

​requirePayment

Overview

Installation

Functions

atxpAccountId

requirePayment