NEW! |One API call, clean data back. No scrapers needed.Get 10,000 Free Tokens →

Developer platform

FineProxy API & MCP

Automate proxy operations from your code or connect an AI agent. See what is supported, where safeguards apply, and how to audit an existing integration before switching providers.

REST API49 OpenAPI operations
MCP server49 agent tools
AccessScoped API keys

One platform, two ways to automate

API and MCP use the same scoped FineProxy keys and expose the same customer workflows. Choose based on who will operate them: your application or an AI agent.

REST · OpenAPI 3.1

Build FineProxy into your application

Use documented HTTP endpoints from a backend, script, CI job, internal panel, or no-code workflow. The current client specification is available in the dashboard.

Best when your code must:
  • Run deterministic workflows without an AI model
  • Validate request and response shapes against OpenAPI
  • Control retries, queues, logs, and deployment yourself
Open API documentation

JSON-RPC 2.0 · Streamable HTTP

Give an AI agent controlled access

Connect Cursor, Claude, VS Code, Cline, n8n, or another MCP client to the FineProxy server. The agent receives tools allowed by the API key scopes.

Best when you want an agent to:
  • Inspect inventory, services, usage, and support history
  • Quote and perform approved service operations
  • Diagnose failures and explain recommended changes
Open MCP setup in the dashboard

Audit an existing integration before you migrate

Download one Markdown file, attach it to a coding agent together with your repository, and run the prepared audit prompt. The first pass is read-only: it identifies compatibility, adapters, blockers, and the exact code that would need to change.

Read-only migration audit prompt
Read the attached FineProxy Agent Pack and inspect this repository.

Do not modify code during the first pass.

Find every place where the current proxy provider is configured or called. Compare each workflow with documented FineProxy capabilities. Report:
1. Fully compatible workflows.
2. Workflows that need an adapter or data transformation.
3. Unsupported or unclear behavior.
4. Required FineProxy API permissions.
5. Exact files and code paths that would change.
6. Authentication and secret-storage changes.
7. A staged migration plan with rollback.
8. Integration tests needed before cutover.

Do not invent endpoints. Mark anything not confirmed by the Agent Pack or the current OpenAPI specification as a question.

The audit should verify

  1. 01Where the current provider is initialized and called
  2. 02Authentication and secret-storage differences
  3. 03Service purchase, renewal, cancellation, and IP update flows
  4. 04Proxy list formats, protocols, ports, and authorization modes
  5. 05Country selection, allowlists, and connection limits
  6. 06Pagination, retries, idempotency, errors, and rate handling
  7. 07Billing, usage analytics, support, and webhook dependencies
  8. 08A file-by-file migration and test plan without editing code

For endpoint-level implementation, also give the agent the current OpenAPI file downloaded from your dashboard. The Agent Pack intentionally contains no credentials or private account data.

What you can automate

The public layer explains complete workflows rather than reproducing every endpoint. Use the live OpenAPI specification when implementing individual requests.

01

Purchase and provisioning

Discover live stock, calculate an exact country mix, and place an order from the dashboard wallet.

  • List available countries and current IP inventory
  • Quote a multi-country package without committing funds
  • Purchase with a price guard and idempotency key
02

Service management

Operate active services without waiting for a support ticket when the plan supports the requested action.

  • Renew, suspend, restore, or cancel services
  • Replace or add IPs and update credentials
  • Manage auto-renewal, allowlists, and connection add-ons
03

Analytics and diagnostics

Use account and service telemetry to investigate load, reliability, and destination behavior.

  • Read usage overviews and time series
  • Inspect top destinations and error categories
  • Receive diagnostics and operational recommendations
04

Billing and support

Connect proxy operations with the financial and support workflows around them.

  • Read invoices and download invoice PDFs
  • Start a wallet deposit and check its status
  • Create, read, reply to, and close support tickets
05

Proxy access

Retrieve the settings applications need to connect through purchased proxies.

  • Read rotating-proxy connection configuration
  • Change service login and password
  • Manage per-IP connection limits in the allowlist
06

Events and account

Keep external systems synchronized and inspect security-relevant account information.

  • Configure webhooks and delivery handling
  • Read profile data, caller IP, and login history
  • Manage API keys with narrowly selected permissions

What the platform will not do

FineProxy automation is intentionally bounded. Access is determined by the key, the service plan, live inventory, and explicit safety checks.

No access outside granted scopes

A tool or endpoint cannot read or change a resource unless the API key includes the required permission.

No spending without wallet:spend

Purchases, renewals, and paid IP updates remain unavailable when the financial scope is not present.

No silent destructive actions

Irreversible operations require an explicit confirmation flag. They cannot happen as a side effect of a read request.

No source-code access through MCP

FineProxy MCP operates the customer account. To audit a script, your coding agent must also be given access to that script or repository.

No guarantee of unsupported inventory

Country availability and quantities are checked against live stock. Automation cannot order inventory that is not available.

No partner API for inactive partners

The partner specification and reporting endpoints are shown only when the account has active partner status.

Connect an agent in minutes

Create a dedicated API key in the dashboard, select only the scopes the agent needs, and place the MCP configuration in your client. Keep the real key in a secret or environment variable.

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

OpenAPI 3.1

Use the live specification for implementation

The dashboard renders the curated client OpenAPI 3.1 specification, request examples, response schemas, and generated client snippets. Active partners also receive a separate partner specification.

View interactive API reference

Choose the smallest useful permission set

Read and write access are separated. Start with read-only scopes for discovery and migration audits, then add write or financial access only to the workflow that requires it.

customer:read

Read customer profile and account information.

customer:write

Update customer information.

wallet:read

View wallet balance and wallet data.

wallet:deposit

Create and monitor wallet deposits.

wallet:spend

Allow automation to spend wallet funds.

services:read

View services, proxy settings, and service state.

services:write

Create or modify services and add-ons.

tickets:read

Read support tickets and their messages.

tickets:write

Create, reply to, update, or close tickets.

catalog:read

Read products, options, countries, and current stock.

usage:read

Read service usage and diagnostic analytics.

webhooks

Create and manage webhook subscriptions.

Security defaults worth keeping

  • Create a separate API key for each application or agent so it can be revoked independently.
  • Begin an audit with read-only scopes. Add services:write or wallet:spend only after reviewing the proposed plan.
  • Store keys in environment variables or a secrets manager, never in source code, prompts, screenshots, or committed MCP configuration.
  • Use the quoted expected total for purchases. A price change rejects the operation instead of silently charging more.
  • Reuse an idempotency key when retrying a timed-out financial request so the same operation cannot be charged twice.
  • Review webhook signatures and delivery history before making events part of a critical workflow.

Start with visibility, then grant control

A read-only audit answers whether the migration is feasible without exposing financial or write access. Once the plan is approved, create a narrowly scoped production key and implement against the live OpenAPI specification.