Webshare

The official Webshare MCP server.

CommunityOnlineNo sign-inGlobalFreeCan modify data

What it can do

  • Get Profile: Get the account's profile: who it belongs to and how it is set up. Use to read the name, email and preferences on the account, and to check when it was registered. Returns those, the acco
  • List Plans: List every plan on the account, active, expired and cancelled. Use to see the subscription history, to check what a plan holds, or to find the plan ids the plan-scoped tools take. Returns
  • Get Plan: Get detailed information about a specific subscription plan. Use after list_plans to examine plan configuration, pricing, quotas and usage limits. Returns the same shape as a list_plans entr

What data it sees

Do you need an account

No: the server works without sign-in

The official Webshare MCP server. Connect your Webshare account and ask about it in plain language: your proxy list and configuration, bandwidth and error statistics, plans and subscription, billing history, notifications, and the proxy catalogue with live pricing. You sign in with your Webshare account through OAuth, so there is no API key to copy. The consent screen asks for read access by default; actions that change something, such as refreshing your proxy list, replacing proxies or managing IP authorizations, only work if you allow write access there. Every connected app can be seen and revoked under Integrations → Connected Apps in the Webshare dashboard.

How to connect

How to connect Webshare to Claude

The server address to paste into Claude settings:

https://proxy-manager--webshare.run.tools

  1. Open Claude (claude.ai or the desktop app).
  2. Go to Settings → Connectors.
  3. Click Add custom connector.
  4. Paste the server address copied below into Remote MCP server URL and click Add.
  5. In a chat, click + → Connectors and switch the new connector on.

Custom connectors are available on Free, Pro, Max, Team and Enterprise plans (Free is limited to one). On Team and Enterprise an organization Owner adds the connector first under Organization settings → Connectors.

Authorization

After you click Add, a sign-in window for the service opens. Sign in with your own account and approve access. Claude never sees your password.

How to connect Webshare to ChatGPT

The server address to paste into ChatGPT settings:

https://proxy-manager--webshare.run.tools

  1. Open ChatGPT in a browser (chatgpt.com). A Plus, Pro, Business, Enterprise or Edu plan is required.
  2. Turn on developer mode once: Settings → Apps → Advanced settings → Developer mode.
  3. Open Settings → Connectors and click Create.
  4. Fill in the form: Name (anything), Description (one line about what the service does), MCP server URL (copy it below).
  5. Under Authentication choose OAuth if the service requires sign-in, otherwise None. Click Create.
  6. In a new chat open + → Apps/Connectors and enable the connector.

OpenAI has renamed this section before (Connectors → Apps/Plugins). If the label differs, search settings for "developer mode". On Business/Enterprise workspaces an admin must allow custom connectors first.

Authorization

On first use ChatGPT opens the service's sign-in window. Sign in and approve access.

How to connect Webshare to Cursor

The server address to paste into Cursor settings:

https://proxy-manager--webshare.run.tools

Fastest: click Open in Cursor below and confirm the prompt.

Manually:

  1. In Cursor open Settings → Cursor Settings → MCP and click Add new global MCP server.
  2. Paste the JSON copied below into ~/.cursor/mcp.json (per project: .cursor/mcp.json in the repo root).
  3. Save the file. The server appears in the MCP list; authorize it there if asked.

Authorization

If the service needs sign-in, an authorize button appears next to the server in the MCP list.

Server tool list (37)

Raw names from tools/list. Only developers need these.

get_profileGet the account's profile: who it belongs to and how it is set up. Use to read the name, email and preferences on the account, and to check when it was registered. Returns those, the account status and how complete the profile is. The `id` it returns belongs to the email preferences row and is not the account id other tools take: those default to the authenticated account when `user_id` is left out.
list_plansList every plan on the account, active, expired and cancelled. Use to see the subscription history, to check what a plan holds, or to find the plan ids the plan-scoped tools take. Returns each plan's product, proxy count and countries, bandwidth limit, status, monthly and yearly price, and its refresh, replacement and subuser quotas. The billing term and the renewal dates belong to the subscription, not to a plan: read them from get_subscription.
get_planGet detailed information about a specific subscription plan. Use after list_plans to examine plan configuration, pricing, quotas and usage limits. Returns the same shape as a list_plans entry: product, proxy allocation, bandwidth limit, prices, quotas and feature flags. Auto-renewal and the period dates belong to the subscription: read them from get_subscription.
get_subscriptionGet the account's current subscription. Use for a quick overview of the account's billing state: term, current period dates, renewals_enabled, free credits, failed payments, account discount, promotion, and whether the subscription is paused or throttled. It carries no plan detail, no proxy counts and no bandwidth: those are in list_plans and get_plan.
cancel_auto_renewalCancel auto-renewal for a customer's PAID subscription. CAUTION: This cancels auto-renewal for the ENTIRE subscription, affecting all plans. When auto-renewal is active, this call disables it and clears the payment method; the subscription stays usable until `subscription.end_date` and then expires. The customer can re-enable later by adding a payment method and choosing a plan. Idempotent: if auto-renewal is already off, the tool returns `state='already_disabled'` WITHOUT clearing the payment method or triggering any change. NOT FOR A FREE PLAN. A free plan does not renew, so there is nothing to cancel and the call is rejected with `code='cannot_modify_free_plan_renewal'`. `get_subscription` shows which plan the account is on. NOT A WAY TO DELETE A SAVED CARD. Clearing the payment method is how the cancellation is implemented, not what this tool is for. A customer who only wants their card removed needs `remove_payment_method`. Use when a customer explicitly requests to cancel their auto-renewal or subscription.
get_billing_infoGet the billing details saved on a customer's account. Returns the billing name, the postal address and the billing email, and nothing else: no tax id, and no invoice. The payment records are in list_transactions. Use when investigating billing questions, invoice requests, or payment issues. Read-only: there is no tool for editing billing details, the customer does that from the dashboard.
list_payment_methodsList the payment methods saved on the account (credit cards, PayPal, etc.). Use when a payment has failed, or to work out which card is the one being charged. Returns the type, brand, last 4 digits, expiry and billing address of each card. No card is marked as the default: the one being charged is the subscription's payment_method. Read-only. To delete the saved card use `remove_payment_method`; adding or replacing one is a dashboard flow, there is no tool for it.
list_pending_paymentsList the account's pending and unpaid invoices and payment attempts. Use when a payment failed, a card was declined, or a balance is outstanding. Returns each attempt's status, its failure_reason, the plan and term it was for, whether it was a renewal, and when it was created and completed. There is no retry schedule: a failed attempt says why it failed, not when it will be tried again.
list_transactionsList the account's billing history: charges, refunds and credits. Use to produce an invoice history, to look into a disputed charge, or to find a payment record. Returns each transaction's amount, credits used and gained, refund amount and date, its reason, the payment method and the line items it paid for. Status is only 'completed' or 'refunded': a failed charge never becomes a transaction, those are in list_pending_payments.
remove_payment_methodDelete the card saved on a customer's account. Use when the customer asks for their card to be removed and nothing else. It takes no card id: it removes the card saved on the subscription, the one being charged. The customer can add a new one from the dashboard afterwards. Idempotent: with no card saved the tool returns `state='no_card_saved'` and changes nothing, so `state` tells whether a card was actually deleted. ONLY WORKS WHILE NO PAID PLAN IS ACTIVE. On a paid plan the call is rejected with `code='paid_plan_active'`, because the card is what pays the renewal. That customer wants `cancel_auto_renewal` instead, which stops the renewal and clears the card together.
get_bandwidth_statsGet bandwidth usage and request stats for one or more of the customer's plans. Use when customers ask about data usage, bandwidth consumption, or how many proxies/countries they're hitting. Each record in the response is scoped to a single plan_id and either contains `bandwidth`, `requests`, and `usage_summary` (successful fetch) or carries a `reason` field (plan_not_accessible / stats_service_unavailable) when that specific plan's fetch failed. Multi-plan customers: pass a list of plan ids. The response keeps one record per plan, in the order passed. Duplicate ids are silently deduped. The response carries no cross-plan totals; each field's description says which numbers are summable, which need recomputation from totals, and which should not be averaged. If one plan in the list fails, its record is a `FailedBandwidthStat` (plan_id + reason) and the other records still return data; the top-level `success` stays True.
get_error_statsGet error statistics with troubleshooting guidance for one or more of the customer's plans. Use when customers report failures, errors, or ask why their proxies aren't working. Each record in the response is scoped to a single plan_id and either contains an `errors` object with counts and per-reason breakdown (successful fetch) or carries a `reason` field (plan_not_accessible / stats_service_unavailable) when that specific plan's fetch failed. Multi-plan customers: pass a list of plan ids. The response keeps one record per plan, in input order. Duplicate ids are silently deduped. To get a cross-plan picture, merge `error_breakdown` by `reason`, sum `count`, and recompute `failure_rate` / `percentage` from summed totals — see the field descriptions. Concentrating errors on a single plan is itself a signal: if the customer has multiple plans and one of them carries most failures, surface that to the customer rather than merging into a single rate that hides the pattern. If one plan in the list fails, its record is a `FailedErrorStat` (plan_id + reason) and the other records still return data; the top-level `success` stays True.
list_proxiesList proxies that belong to a single plan, paginated, with filtering support. Use to show available proxies, check proxy counts, or filter by country/validity. Each response is scoped to the `plan_id` you pass. For multi-plan customers, call this tool once per plan and merge the results — pagination is per-plan, do not assume cross-plan totals. Mode caveat: backbone mode (residential) only supports `country_code__in`. The other filters are silently ignored when `mode=backbone`; `search`/`ordering` actively raise 400.
get_proxy_configGet the proxy configuration of a plan. Use to see how the plan's proxies are spread across countries and how they are set to connect and rotate. Returns the country distribution, allocated against requested, the connection mode, the rotation settings and the current allocation status. It describes the shape of the list, not its contents: the addresses themselves are in `list_proxies`.
get_proxy_config_statsGet a summary of the proxy inventory available to a plan. Use before changing where a plan's proxies live, to see what can actually be allocated, and to judge how spread out the current ones are. Returns the available countries, the IP ranges by subnet size (/24, /16, /8) and the ASN distribution. These are counts of what the pool holds, not the plan's own proxies: for those use `list_proxies`.
get_proxy_config_statusGet the allocation status and the proxy credentials of a plan. Use to tell whether a plan's proxies are ready to use, and to read the username and password they authenticate with. Returns state (pending, processing or completed), the per-country allocation, and the credentials, which are secret: pass them on only to the account holder. It says nothing about which addresses were allocated, only how many per country; for the addresses themselves use `list_proxies`.
list_proxy_replacementsList bulk proxy replacement requests for a single plan, paginated. Use to view a plan's replacement history or investigate replacement issues. Each record describes a bulk replacement operation (not a single proxy): what was replaced (`to_replace`), the rules used to pick replacements (`replace_with`), counts (`proxies_removed`, `proxies_added`), current `state` (pending, processing, completed, failed), `reason`, `dry_run` flag, and `created_at` / `completed_at` timestamps. To see the individual old-proxy records produced by these operations, use `list_replaced_proxies` instead. Records include BOTH customer-initiated replacements (`reason='proxy_replaced'`) AND system-initiated ones (`auto_invalidated`, `auto_deleted`, `list_rotated`, etc.). When the customer asks "what did I do?", filter by `reason='proxy_replaced'`; when they ask "why was my proxy taken?", the auto-* reasons explain it.
get_proxy_replacementGet one bulk replacement request by id. Use after `create_proxy_replacement` to poll a request until it reaches a terminal state, or after `list_proxy_replacements` to look at one in the history. Returns the `state` (pending, processing, completed or failed), the `to_replace` / `replace_with` specification, `proxies_removed`, `proxies_added`, the `reason`, and the `created_at` / `completed_at` timestamps. It describes the request, not its outcome on the list: for the addresses that were actually swapped out, use `list_replaced_proxies`.
list_replaced_proxiesList proxies that have been replaced on a single plan (old proxies no longer in active pool). Use to view historical replaced proxy list, investigate why proxies were replaced, or verify replacement completion. Unlike list_proxy_replacements which shows replacement requests, this shows the actual old proxy records that were removed from service. Returns records including: replaced proxy IP/port/country_code (`proxy`, `proxy_port`, `proxy_country_code`), the new proxy assigned (`replaced_with`, `replaced_with_port`, `replaced_with_country_code`), the `reason` for replacement, and `created_at` timestamp. Records include BOTH customer-initiated replacements (`reason='proxy_replaced'`) AND system-initiated ones (`auto_invalidated`, `auto_deleted`, `list_rotated`, etc.). When the customer asks "why was my proxy taken?", the auto-* reasons explain it without the customer having done anything.
list_ip_authorizationsList IP authorizations on a plan's proxy access whitelist. Use when diagnosing connection issues or auditing which IPs the customer has pre-authorized for a specific plan. IP authorization is the default auth mode on proxies — only connections from whitelisted IPs are accepted (the alternative is username/password). Each entry contains: the IP address, when it was added (`created_at`), and when it was last seen sending traffic through the proxies (`last_used_at`). An authorization with `last_used_at` far in the past is a candidate for cleanup. Use `ip_address` for an exact-match check on a single IP; use `search` for a partial substring lookup when the customer remembers only part of an address.
get_ip_authorizationGet one authorized IP on a plan, by id. Use after `list_ip_authorizations` to confirm a single entry, usually to check `last_used_at` before removing one that looks unused. Returns the same shape as a list entry: `ip_address`, `created_at` and `last_used_at`. It cannot tell you whether the address still belongs to the person who added it, and a null `last_used_at` means never used, not recently unused.
list_notificationsList the in-product notifications on the account (alerts, reminders, billing follow-ups). Use when something looks like it went unnoticed, or to see what the product has already said about the account. Notifications are polymorphic — the `type` field identifies which variant was emitted, and the `context` object carries the type-specific payload of that variant: - `80_percent_bandwidth_used` / `100_percent_bandwidth_used`: plan reached the bandwidth ceiling (80% variant also carries `proxy_usage_rate`). - `high_concurrency_error` / `projected_proxy_usage_over_100`: customer is trending over a limit — `projected_bandwidth_gbs` shows the forecast. - `too_many_forbidden_host_error`: customer hit blocked hosts repeatedly (compliance). - `too_much_bandwidth_too_little_proxies`: plan sizing hint — bandwidth is being used by too few proxies. - `unlimited_bandwidth_gets_throttled`: customer on unlimited-bandwidth plan is being throttled due to usage patterns. - `subscription_renew_failed`: `effect` explains the customer impact ('converted_to_free_plan', 'proxies_stopped_working', or null while the renewal payment is still in the retry window). - `subscription_cc_will_expire_soon` / `subscription_will_expire_soon` / `subscription_renewal_upcoming`: billing timing reminders. `subscription_will_expire_soon.context.before` is the days-before bucket (1, 2, or 7). - `reminder_to_use_proxy` / `question_is_added`: engagement + verification flow nudges. `is_dismissable=False` means the notification is system-pinned and cannot be dismissed. Non-null `dismissed_at` means the user (or automation) already dismissed it.
get_notificationRetrieve a single notification by id with its full typed context. Use after `list_notifications` to inspect the exact variant details on record. Returns the same discriminated-union shape as a list entry — `context` is already typed per the notification's `type`, so specific fields (e.g. `proxy_usage_rate`, `effect`, `before`) can be read directly without guessing.
list_verificationsList the active verification flows on the account. Relevant when the account is suspended, when proxies stop working, or on a '403 Forbidden': a verification flow is what holds access back until it clears. Returns verification type (acceptable_use_violation, abuse_report, fraudulent_payment), state (inflow, successful_verification, failed_verification), and whether ID verification is required.
get_verificationGet one verification flow on the account by id. Use after list_verifications to see what a particular verification asks for and how far it got. Returns full verification details including type, state, required documents, and any error messages or rejection reasons.
list_verification_categoriesList the verification categories and document types the system accepts. Use to see which documents you can submit (e.g., government ID, proof of address, business registration), so you know what to prepare before starting. It lists what the system accepts in general, not what any one verification is asking for: that is in `get_verification`.
get_verification_limitsGet the access limits and restrictions currently on the account. Relevant when proxies are not working, on a '403 Forbidden', or on any access problem. Returns proxy_state, one of 'active' (normal access), 'paused' (proxies disabled until verification clears), or 'limited' (reduced concurrency/thread limit).
get_verification_thresholdsGet the thresholds that trigger a verification on the account. Returns spending limits, bandwidth thresholds, and activity levels that trigger verification requirements. Use to explain why a verification was raised, or to see how close the account is to one.
list_verification_questionsList the verification questions on the account, answered and unanswered. Use to see what is still pending before a verification can clear. Returns question id, question text, the submitted answer (null when unanswered), and the verification flow id each question belongs to.
view_suspensionView the suspension details of the account. Use immediately when the account looks suspended or every proxy stopped working at once. Always returns a structured response on success: - is_suspended=True with populated `suspension` (reason + created_at) when the account is suspended. - is_suspended=False with `suspension=None` when there is no active suspension. The `message` field carries a plain-language summary of why. It does not say when the suspension will lift, and there is no tool that does: an appeal goes through verification.
list_abuse_reportsList the abuse reports filed against the account. Relevant when the account is suspended or restricted, since an abuse report is usually what started it. Each report carries the description it was filed with (`content`) and the `flow` id of the verification flow it opened; pass that flow id to `get_verification` to see where it ended up.
get_customer_contextGet an account overview: profile, subscription status, active plans, and billing alerts. For a general look at the account, or as the starting point for a question about it. RETURNS: - user: identity, email verification status, account age, last activity - subscription: billing term/dates, paused/throttled status, payment failures, credits, discounts - active_plans[]: proxy type/count/countries, bandwidth, pricing, quotas, features - billing_alerts: consolidated "is anything wrong with the billing right now?" signal. `billing_alerts.has_failing_payment` is True when a payment is failing (card declined, insufficient funds, etc.), the most common billing problem, and `billing_alerts.failing_payments[]` carries the detail of each. NOT INCLUDED: proxy inventory (list_proxies), usage and error stats (get_bandwidth_stats, get_error_stats), the full billing history (list_payment_methods, list_transactions), the full detail of pending payments (list_pending_payments), and account restrictions (view_suspension, list_verifications).
diagnose_billing_issueDiagnose the account's current billing health in one call. For questions like 'why am I being charged', 'why aren't my proxies working', 'why is my subscription ending' or 'I was charged but didn't get my plan'. It checks payments, payment methods, subscription state, verifications, suspension and notifications together and returns the issues it finds, each with its evidence. RETURNS: - status: overall health ('critical', 'action_required', 'informational', 'all_clear'). - issues[]: the detected issues, most important first. Each issue is a discriminated union by `category`, carrying only the evidence fields relevant to that category. CATEGORIES: - payment_stuck_unallocated: the account was charged but the purchase was not provisioned. Critical. Refund or manual provisioning is owed. - account_suspended: account is locked out of service. - card_failed: a payment was declined. is_initial_purchase tells a first-purchase failure from a renewal failure. Severity depends on failed_payment_times (== 2 = critical because proxies are throttled to ~1 MB/month). - no_payment_method: no card on file and the subscription needs one soon. - verification_blocking: an open verification flow is preventing normal service. - card_expiring_soon: the card on file will expire and renewals will start failing. - subscription_paused: the subscription is paused (proxies disabled). - subscription_throttled: the subscription is throttled (reduced speeds/concurrency). - payment_processing: a payment is in-flight; usually clears within minutes. NOT INCLUDED: plan and proxy inventory (list_plans, list_proxies), the full history of each payment (list_pending_payments, list_transactions), and verification questions and answers (list_verification_questions, get_verification).
get_customer_timelineGet a chronological narrative of recent activity on the account. For "what has been happening with this account", a recent problem, or whether it has happened before. Returns one timeline stitched across account, subscription, payment, verification, appeal, abuse, and notification sources in a single call. `timeline.summary` and `timeline.highlights` summarise the critical and notable events; `timeline.events` carries the event-level detail. Plan references surface `details.product_id` (stable catalog identifier), never raw PCP proxy_type/pool_filter pairs. Caveat: PCP filters out verification flows in the `created` (pre-admin-approval) state from the list endpoint, so very early-stage verifications won't appear until they reach `inflow`.
list_proxy_catalogReturn the static catalog of all purchasable Webshare proxy products. Answers 'what does Webshare sell?'. Each product carries a stable `product_id`, which get_pricing and get_customize_options take, plus a description and high-level metadata. Configurable bounds (min/max bandwidth, supported features, country availability) are not in the catalog; get_customize_options returns them. RETURNS: - products: 8 entries — `free` (auto-provisioned starter, not purchasable), datacenter (Proxy Server Shared/Private/Dedicated), static residential (Static Residential Shared/Private/Dedicated), and rotating residential (Residential). - country_sets: {'residential': [~167 ISO codes for the rotating residential product], 'free': ['ZZ'] (placeholder country for free plan — free customers cannot pick a country)}. - sanctioned_countries: payment-side review countries (RU, BY, CU, IR, KP, SY). - minimum_charge_usd: smallest billable amount on a single transaction. - available_terms: monthly + yearly. - notes: cross-cutting business rules that apply to every configuration, such as the free-plan special case and other constraints not encoded in the schema. - catalog_version: ISO date this catalog was last validated. DOES NOT INCLUDE: verified proxies (a configuration of `proxy_server_shared` surfaced via the verified_available_site_checks field — not a separate product), per-customer or per-configuration bounds (get_customize_options), or the price of a configuration (get_pricing).
get_customize_optionsResolve the runtime customization bounds and live country availability for a product. Takes a `product_id` from list_proxy_catalog and returns which values are valid for that product right now, for this customer. It answers questions like 'how many proxies can I buy?', 'is country X currently available?', 'what bandwidth tiers can I pick?', and 'does my account have the custom-bandwidth experiment?'. get_pricing refuses a configuration outside these bounds with a 400. BEHAVIOR IS PER-CUSTOMER: bounds reflect the customer behind the request (their existing plans, their experiment cohort, their proxy_list). Two different customers calling with the same `product_id` may receive different bounds — this is intentional, not a bug. Without authentication the response reflects a hypothetical brand-new customer. VERIFIED MODE: pass `required_site_checks` to learn the locked-down bounds (fixed bandwidth tier, no rotation, no refreshes, no replacements). Only valid for products whose catalog entry advertises non-empty `verified_available_site_checks` — passing it for any other product returns a 400. RATE LIMIT: the endpoint is rate-limited. The bounds depend on the product, the country distribution and the site checks, not on the quantities chosen within them.
get_pricingQuote a specific proxy plan configuration. The actual price of a chosen `product_id`, country distribution and add-ons, for a customer comparing real prices or about to buy. What Webshare sells in general is in the catalog (list_proxy_catalog), and a configuration outside the bounds get_customize_options reports is refused with a 400. BEHAVIOR: `behavior="add"` prices a new plan alongside the customer's current ones; `behavior="upgrade"` prices changing the plan named in `plan_id`. The two return different numbers for the same configuration. TERMS: pass `term="monthly"` or `term="yearly"` for a single quote, or omit `term` to get both terms in the same response, side by side. FREE PRODUCT: rejected with a ValidationError — the free tier is auto-provisioned and not purchasable. AUTHENTICATED VS ANONYMOUS: with `user_id` the response carries `paid_today`, `credits_added`/`credits_used` (relevant for upgrades), and `tax_breakdown` (when the customer has a payment method on file). Without user_id the response reflects a first-time anonymous purchase quote.