# FineProxy Agent Pack

Version: 2026-09-22

Use this file to assess whether an existing proxy integration can migrate to FineProxy. It contains no API key, account data, or private endpoint.

## Sources of truth

- Interactive client API documentation: `https://fineproxy.org/account_new/docs`
- MCP setup: `https://fineproxy.org/account_new/mcp`
- Current client OpenAPI specification: download it from the API documentation in the customer dashboard.
- Create and manage API keys: `https://fineproxy.org/account_new/settings`
- MCP endpoint: `https://fineproxy.org/account_new/api/v1/mcp`

Never invent an endpoint from this overview. Use the current OpenAPI specification for request paths, schemas, parameters, and responses.

## Platform summary

- REST API: OpenAPI 3.1, 49 documented customer operations.
- MCP: 49 tools over stateless JSON-RPC 2.0 and Streamable HTTP.
- Authentication: bearer API keys created in the customer dashboard.
- API and MCP use the same scoped permissions.
- Partner API documentation is visible only to accounts with active partner status.

## Supported workflows

### Purchase and provisioning

- List countries and live IP inventory.
- Quote an exact multi-country package without purchasing.
- Purchase from the dashboard wallet with a price guard and idempotency key.

The standard MCP purchase sequence is:

1. `list_countries`
2. `quote_composite`
3. `order_composite`

### Service management

- Read and manage services.
- Renew, suspend, restore, or cancel when supported.
- Enable or disable auto-renewal.
- Replace or add IP addresses.
- Change service credentials.
- Read and manage allowlist limits.
- List, purchase, and cancel compatible add-ons.

### Analytics and diagnostics

- Usage overview and time series.
- Top destinations.
- Error categories.
- Operational recommendations.

### Billing and support

- Read invoices and download invoice PDFs.
- List payment gateways.
- Start a wallet deposit and read its status.
- Create, read, reply to, and close support tickets.

### Proxy access and account

- Read rotating-proxy connection configuration.
- Change service login and password.
- Manage per-IP connection limits in the allowlist.
- Read profile information, caller IP, and login history.
- Configure webhooks.

## Permission scopes

- `customer:read` — read customer and account information.
- `customer:write` — update customer information.
- `wallet:read` — read wallet information.
- `wallet:deposit` — create and monitor deposits.
- `wallet:spend` — spend wallet funds. Treat as a financial permission.
- `services:read` — read services and proxy settings.
- `services:write` — create or modify services and add-ons.
- `tickets:read` — read support tickets.
- `tickets:write` — create, reply to, update, or close tickets.
- `catalog:read` — read products, options, countries, and stock.
- `usage:read` — read usage and diagnostics.
- `webhooks` — manage webhook subscriptions.

Begin a migration audit with read-only permissions. Add write or financial permissions only after the proposed changes have been reviewed.

## Safety behavior

- Financial tools require `wallet:spend`.
- Purchases carry the expected quoted total. A price mismatch rejects the operation.
- Irreversible operations require explicit confirmation.
- Financial retries use an idempotency key so the same operation is not charged twice.
- Live inventory, plan eligibility, and account permissions can prevent an otherwise valid operation.
- FineProxy MCP operates the customer account. It does not gain access to source code unless the user separately gives the coding agent access to a repository.

## MCP configuration template

```json
{
  "mcpServers": {
    "fineproxy": {
      "url": "https://fineproxy.org/account_new/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer fb_YOUR_API_KEY"
      }
    }
  }
}
```

Store the real key in an environment variable or secrets manager. Do not commit it with the MCP configuration.

## Migration compatibility checklist

Inspect the existing integration for:

1. Provider client initialization and all provider-specific imports.
2. Authentication headers, credentials, environment variables, and secret storage.
3. Purchase, renewal, cancellation, and IP replacement workflows.
4. Country identifiers and inventory assumptions.
5. Proxy list formats, protocols, ports, usernames, passwords, and IP allowlisting.
6. Pagination and filtering.
7. Retry behavior, timeout handling, and idempotency.
8. Error models and rate handling.
9. Usage analytics and diagnostics.
10. Billing, invoices, and deposits.
11. Support-ticket integration.
12. Webhooks and event payload assumptions.
13. Tests, fixtures, mocks, and CI secrets tied to the current provider.

Classify every workflow as:

- Compatible without changes.
- Compatible through a configuration change.
- Requires an adapter or data transformation.
- Requires a different operational workflow.
- Unsupported or not confirmed by the current documentation.

## Required audit output

The audit should include:

1. An inventory of every current-provider dependency.
2. A workflow-by-workflow compatibility assessment.
3. Required FineProxy scopes.
4. Exact files and code paths that would change.
5. Authentication and secret-management changes.
6. Open questions that require the current OpenAPI specification or support confirmation.
7. A staged migration plan with rollback.
8. Integration tests required before cutover.

Do not modify code during the first audit pass.