# Agents

> pay mcp and pay skills — run the Pay MCP server and browse the pay-skills provider catalog.

The Agents group covers the two surfaces an AI agent talks to directly: the MCP server it connects to, and the provider catalog it browses.

For a task-shaped walk-through of attaching an agent client to `pay`, see [Using pay → Pass-through commands](/docs/using-pay/pass-through-commands).

## `pay mcp`

Start the local MCP server (for Claude Code, Cursor, and other MCP-capable clients).

```sh
pay mcp
```

`pay mcp` runs in the foreground and speaks the Model Context Protocol over stdio. Most clients don't launch it directly — `pay setup` writes the MCP config that points the client at `pay mcp`.

The server exposes:

- `pay.search` — query the skills catalog.
- `pay.endpoints` — list endpoints for a service.
- `pay.curl` — paid HTTP request, gated by the client's auth-required policy.
- `pay.balance` — read account balances.
- `pay.validate_provider` — sanity-check a `PAY.md` before publishing.

## `pay skills`

Browse, search, and inspect API providers from the skills catalog.

```sh
pay skills <subcommand>
```

| Subcommand                                   | Purpose                                                |
| -------------------------------------------- | ------------------------------------------------------ |
| [`search`](#pay-skills-search)               | Search by keyword or category.                         |
| [`endpoints`](#pay-skills-endpoints)         | List endpoints for a specific service.                 |
| [`add`](#pay-skills-add)                     | Add a provider source (GitHub org/repo or URL).        |
| [`remove`](#pay-skills-remove)               | Remove a provider source.                              |
| [`list`](#pay-skills-list)                   | List configured provider sources.                      |
| [`update`](#pay-skills-update)               | Refresh the local cache from all sources.              |
| [`provider sync`](#pay-skills-provider-sync) | Sync runtime provider YAMLs into registry `.md` files. |

### `pay skills search`

Search for API providers and endpoints. Matches service names, endpoint paths, and descriptions.

```sh
pay skills search "gemini"
pay skills search "translate text" --category ai_ml
pay skills search --json
```

| Flag                | Type       | Default | Description                                                 |
| ------------------- | ---------- | ------- | ----------------------------------------------------------- |
| `[QUERY]`           | positional | —       | Keyword to search for. Omit to list everything.             |
| `--category` (`-c`) | string     | —       | Filter by category (`ai_ml`, `data`, `compute`, `maps`, …). |
| `--json`            | bool       | `false` | Output as JSON instead of a table.                          |

### `pay skills endpoints`

List all endpoints for a specific service.

```sh
pay skills endpoints bigquery jobs
pay skills endpoints solana-foundation/google/bigquery jobs --json
```

| Flag         | Type       | Default | Description                                         |
| ------------ | ---------- | ------- | --------------------------------------------------- |
| `<SERVICE>`  | positional | —       | Service name or FQN. Required.                      |
| `<RESOURCE>` | positional | —       | Resource name, e.g. `jobs` or `datasets`. Required. |
| `--json`     | bool       | `false` | Output as JSON instead of a table.                  |

### `pay skills add`

Add a provider source — a GitHub `org/repo` or a full catalog URL.

```sh
pay skills add solana-foundation/pay-skills
pay skills add https://catalog.example.com/skills.json
```

| Flag       | Type       | Default | Description                              |
| ---------- | ---------- | ------- | ---------------------------------------- |
| `<SOURCE>` | positional | —       | GitHub `org/repo` or full URL. Required. |

[`pay install`](/docs/toolchain/commands/other#pay-install) (alias `pay add`, short flag `-i`) is a shorthand for the same operation.

### `pay skills remove`

Remove a provider source. Aliases: `rm`.

```sh
pay skills remove solana-foundation/pay-skills
```

### `pay skills list`

List configured provider sources. Alias: `ls`.

```sh
pay skills list
```

### `pay skills update`

Refresh the local skills cache from all sources. Useful after `add` or when a provider has updated its catalog.

```sh
pay skills update
```

| Flag      | Type | Default | Description           |
| --------- | ---- | ------- | --------------------- |
| `--force` | bool | `false` | Bypass the CDN cache. |

### `pay skills provider sync`

Sync runtime provider YAMLs into registry `.md` files. Writes `<out>/<operator>/<origin>/<name>.md` for every input.

```sh
pay skills provider sync providers/google/*.yml --operator solana-foundation
pay skills provider sync providers/google/translate.yml \
  --operator solana-foundation \
  --service-url "https://google-{name}.run.app" \
  --sandbox-service-url "https://sandbox-google-{name}.run.app"
```

| Flag                    | Type       | Default     | Description                                                                                                      |
| ----------------------- | ---------- | ----------- | ---------------------------------------------------------------------------------------------------------------- |
| `<PATHS>...`            | positional | —           | Paths to `.yml` files or glob patterns. Required.                                                                |
| `--operator`            | string     | —           | Operator/aggregator serving these APIs (e.g. `solana-foundation`). Required.                                     |
| `--out` (`-o`)          | path       | `providers` | Output directory.                                                                                                |
| `--origin`              | string     | —           | Override the origin org. Inferred from the parent directory of each input file.                                  |
| `--service-url`         | template   | —           | Template for `service_url` (production). Use `{name}` as placeholder. Falls back to `routing.url` from the YAML. |
| `--sandbox-service-url` | template   | —           | Template for `sandbox_service_url`. Use `{name}` as placeholder.                                                 |