---
title: MCP tools
description: Every Points MCP tool with its OAuth scope, annotations, and input schema. Names, scopes, and schemas generated from code.
url: https://thepoints.io/docs/agents/reference/mcp-tools
audience: [agents, operators, developers]
status: Live
---

# MCP tools

> **Agent Pay status:** Approve does not execute. Execution: not enabled. ACH settlement: not enabled. prepare_payment never moves money. Machine-readable: [/docs/agents/status.json](/docs/agents/status.json).

Names, scopes, and schemas generated from code. Machine-readable: [/docs/agents/reference/mcp-tools.json](/docs/agents/reference/mcp-tools.json).

Server `points-mcp` version `2.2.0`, MCP protocol `2025-11-25`, Streamable HTTP at `https://thepoints.io/mcp`. Every call needs an OAuth access token, and the tool's scope is checked on every call. No tool accepts an account identifier: the account comes from the OAuth grant.

| Tool | Scope | Read-only | Listed by tools/list |
|---|---|---|---|
| [`get_account_summary`](#get-account-summary) | `balances:read` | Yes | Yes |
| [`list_transactions`](#list-transactions) | `transactions:read` | Yes | Yes |
| [`find_savings_opportunities`](#find-savings-opportunities) | `optimize:read` | Yes | Yes |
| [`create_payment_draft`](#create-payment-draft) | `payments:draft` | No | No (retired, fails closed) |
| [`prepare_payment`](#prepare-payment) | `payments:draft` | No | Yes |
| [`get_payment_status`](#get-payment-status) | `payments:status` | Yes | Yes |
| [`get_connection_identity`](#get-connection-identity) | `identity:read` | Yes | Yes |
| [`get_account_status`](#get-account-status) | `module-status:read` | Yes | Yes |
| [`get_agent_pay_policy_vocabulary`](#get-agent-pay-policy-vocabulary) | `module-status:read` | Yes | Yes |
| [`get_wallet_status`](#get-wallet-status) | `module-status:read` | Yes | Yes |

## get_account_summary

**Get account summary.** Read-only balance summary for the connected account. The available balance is unreserved cash, after Agent Pay reserved and escrowed amounts. Sources are labelled sandbox.

- Scope: `balances:read`
- Annotations: `readOnlyHint` true, `destructiveHint` false, `idempotentHint` true, `openWorldHint` false
- Listed by tools/list: yes

Input schema:

```json
{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}
```

## list_transactions

**List transactions.** Read-only sandbox transaction list for the connected account.

- Scope: `transactions:read`
- Annotations: `readOnlyHint` true, `destructiveHint` false, `idempotentHint` true, `openWorldHint` false
- Listed by tools/list: yes

Input schema:

```json
{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}
```

## find_savings_opportunities

**Find savings opportunities.** Read-only sandbox savings suggestions scoped to the connected account.

- Scope: `optimize:read`
- Annotations: `readOnlyHint` true, `destructiveHint` false, `idempotentHint` true, `openWorldHint` false
- Listed by tools/list: yes

Input schema:

```json
{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}
```

## create_payment_draft

**Create payment draft.** Retired. Not listed by tools/list. A direct call fails closed with an explicit message to use prepare_payment.

- Scope: `payments:draft`
- Annotations: `readOnlyHint` false, `destructiveHint` false, `idempotentHint` true, `openWorldHint` false
- Listed by tools/list: no
- Every call returns: `create_payment_draft is no longer an advertised POINTS MCP tool. Refresh tool discovery and use prepare_payment for Agent Pay payment preparation.`

Input schema:

```json
{
  "type": "object",
  "properties": {
    "amountCents": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10000000
    },
    "currency": {
      "type": "string",
      "pattern": "^[A-Z]{3}$"
    },
    "recipient": {
      "type": "string",
      "minLength": 1,
      "maxLength": 160
    },
    "reference": {
      "type": "string",
      "minLength": 1,
      "maxLength": 240
    },
    "idempotencyKey": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{8,120}$"
    }
  },
  "required": [
    "amountCents",
    "currency",
    "recipient",
    "reference",
    "idempotencyKey"
  ],
  "additionalProperties": false
}
```

## prepare_payment

**Prepare agent payment.** Agent Pay entry point. Checks policy, spending controls, and caps, then stages a draft that always needs human approval. It never moves money.

- Scope: `payments:draft`
- Annotations: `readOnlyHint` false, `destructiveHint` false, `idempotentHint` true, `openWorldHint` false
- Listed by tools/list: yes

Input schema:

```json
{
  "type": "object",
  "properties": {
    "amountCents": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10000000
    },
    "currency": {
      "type": "string",
      "pattern": "^[A-Z]{3}$"
    },
    "merchant": {
      "type": "string",
      "minLength": 1,
      "maxLength": 160
    },
    "category": {
      "type": "string",
      "enum": [
        "ai_compute",
        "advertising_marketing",
        "saas_apis",
        "ecommerce_procurement",
        "logistics"
      ]
    },
    "reference": {
      "type": "string",
      "minLength": 1,
      "maxLength": 240
    },
    "idempotencyKey": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{8,120}$"
    },
    "paymentPattern": {
      "type": "string",
      "enum": [
        "standard",
        "sell_side_job",
        "micropayment"
      ],
      "description": "Optional Agent Pay P2 pattern. sell_side_job holds escrow before work; micropayment reserves fee before send and charges only on HTTP 2xx. Never moves money while execution is disabled."
    },
    "policySchemaVersion": {
      "type": "integer",
      "minimum": 1,
      "maximum": 32,
      "description": "Policy schema version from get_agent_pay_policy_vocabulary.policySchemaVersion. Unsupported versions fail closed on spend. Omit only for legacy clients."
    }
  },
  "required": [
    "amountCents",
    "currency",
    "merchant",
    "idempotencyKey"
  ],
  "additionalProperties": false
}
```

## get_payment_status

**Get payment draft status.** Read-only status of a payment draft on the connected account, with read-time expiry applied. executed is always false.

- Scope: `payments:status`
- Annotations: `readOnlyHint` true, `destructiveHint` false, `idempotentHint` true, `openWorldHint` false
- Listed by tools/list: yes

Input schema:

```json
{
  "type": "object",
  "properties": {
    "draftId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120
    }
  },
  "required": [
    "draftId"
  ],
  "additionalProperties": false
}
```

## get_connection_identity

**Get connection identity.** Read-only redacted identity of the connected account and its server-side mappings. No balances or secrets.

- Scope: `identity:read`
- Annotations: `readOnlyHint` true, `destructiveHint` false, `idempotentHint` true, `openWorldHint` false
- Listed by tools/list: yes

Input schema:

```json
{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}
```

## get_account_status

**Get account status.** Read-only account type and module activation status.

- Scope: `module-status:read`
- Annotations: `readOnlyHint` true, `destructiveHint` false, `idempotentHint` true, `openWorldHint` false
- Listed by tools/list: yes

Input schema:

```json
{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}
```

## get_agent_pay_policy_vocabulary

**Get Agent Pay policy vocabulary.** Read-only policy vocabulary: schema version, canonical categories, matching rules, velocity caps, and the allow and block lists for this connection.

- Scope: `module-status:read`
- Annotations: `readOnlyHint` true, `destructiveHint` false, `idempotentHint` true, `openWorldHint` false
- Listed by tools/list: yes

Input schema:

```json
{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}
```

## get_wallet_status

**Get wallet status.** Read-only stored wallet status (staging) for the connected AI Agent. No balances and no raw wallet identifiers.

- Scope: `module-status:read`
- Annotations: `readOnlyHint` true, `destructiveHint` false, `idempotentHint` true, `openWorldHint` false
- Listed by tools/list: yes

Input schema:

```json
{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}
```