MCP Server
The Webshare MCP server connects AI agents to your Webshare account through the Model Context Protocol (opens in a new tab). Add it to Claude, Cursor or any other MCP client, and your agent can list your proxies, check bandwidth and errors, replace proxies, manage IP authorizations and answer questions about your plan and billing.
It is a hosted server, so there is nothing to install. You sign in with your Webshare account through OAuth, so you don't need an API key.
- Server URL:
https://mcp.webshare.io/ - Transport: Streamable HTTP
- Authentication: OAuth, discovered from the server. No API key or headers needed.
- MCP Registry: listed as
io.webshare/mcp
Connect your client
Pick your client and follow its steps. The same steps are on the MCP Server (opens in a new tab) page of your dashboard.
Run this in your terminal, from your project directory:
claude mcp add --transport http webshare https://mcp.webshare.io/Then start Claude Code, run /mcp, select webshare and choose Authenticate.
Allow access
The first time your client connects, it opens Webshare in your browser:
- Log in to Webshare if asked.
- Check the app name and the permissions it asks for. Clients ask for read access. Tick the Write permissions too if you want your agent to make changes.
- Click Allow Access. Your browser sends you back to your client, and the connection is ready.
Only the account owner can connect apps. If you are logged in as a sub-user or with a staff session, the consent screen shows Only the account owner can connect apps. Use Switch Account to log in as the owner.
The consent screen shows most clients as Not verified by Webshare. This is expected: Claude Code, Claude, Cursor and most other clients register themselves when they first connect. Check that the app name is the one you are connecting and that it returns you where you expect. Claude Code, for example, shows Returns you to localhost on this computer.
The consent link is valid for 10 minutes and can be used once. If you see This link has expired, go back to your client and start the connection again.
Test your connection
Ask your agent one of these to check that everything works:
- List my Webshare proxies grouped by country.
- Find proxies that failed more than 5% in the last 24 hours and suggest replacements.
- What's my projected bandwidth usage this month compared to my current plan?
Permissions
Each connection only gets the permissions (OAuth scopes) you allowed on the consent screen. Your agent only sees the tools those permissions cover, and calls to any other tool are refused.
| Scope | Access | What it allows |
|---|---|---|
proxy:read | Read | Proxy list, configuration, statistics and replacement history. |
account:read | Read | Profile, subscription and plans, notifications and verifications. |
billing:read | Read | Billing details, payments and payment methods. |
catalog:read | Read | Webshare products and pricing. |
proxy:write | Write | Refresh the proxy list, replace proxies, allocate unallocated proxies and change IP authorizations. |
billing:write | Write | Cancel auto-renewal and remove the saved payment method. |
Clients ask for the four read scopes, and those are ticked on the consent screen. The write scopes are listed but not ticked. Tick them only if you want your agent to change your proxies or billing. You can also untick scopes you don't want to give, as long as at least one stays ticked.
To change the permissions of a connected app later, disconnect it and connect it again.
No permission lets an agent buy, renew or upgrade a plan, add a payment method, manage API keys, or change your login and security settings. Those stay in the dashboard.
Tools
These are the tools your agent can call. The Scope column shows the permissions each tool needs.
Tools that need a write scope change your account.
Account & billing
| Tool | Scope | Description |
|---|---|---|
get_profile | account:read | Your profile: name, email and account details. |
get_subscription | account:read | Subscription summary: term, current period, auto-renewal, credits, and whether it is paused or throttled. |
list_plans | account:read | All your plans (active, expired and cancelled) with proxy counts, countries, bandwidth, prices and quotas. |
get_plan | account:read | One plan in detail. |
get_billing_info | billing:read | Billing name, postal address and billing email. |
list_payment_methods | billing:read | Saved payment methods: type, brand, last 4 digits and expiry. |
list_pending_payments | billing:read | Pending and failed payment attempts, with the reason a payment failed. |
list_transactions | billing:read | Billing history: charges, refunds and credits. |
diagnose_billing_issue | account:read
billing:read | Checks payments, payment methods, subscription state, verifications and suspension in one call, and lists any problems found, most urgent first. |
cancel_auto_renewal | account:read
billing:write | Turns off auto-renewal for the whole subscription and clears the payment method. Your plans keep working until the end of the current period. |
remove_payment_method | account:read
billing:write | Removes the saved card. Only works when no paid plan is active. |
Usage & statistics
| Tool | Scope | Description |
|---|---|---|
get_bandwidth_stats | proxy:read | Bandwidth use and request counts for one or more plans, with an optional date range. |
get_error_stats | proxy:read | Error counts and a breakdown by reason for one or more plans, with troubleshooting guidance. |
Proxies & configuration
| Tool | Scope | Description |
|---|---|---|
list_proxies | proxy:read | Proxies on a plan, filtered by country, validity, ASN or address. |
get_proxy_config | proxy:read | A plan's proxy configuration: country allocation, connection mode, rotation and authentication settings. |
get_proxy_config_stats | proxy:read | Available countries, IP ranges and ASNs for a plan. |
get_proxy_config_status | proxy:read | Allocation state, country allocations and proxy credentials for a plan. |
refresh_proxy_list | proxy:write | Replaces a plan's proxies with new ones from the pool. Uses the plan's refresh quota. |
allocate_unallocated_countries | proxy:write | Moves a plan's unallocated proxies into the countries you choose. |
Proxy replacements
| Tool | Scope | Description |
|---|---|---|
list_proxy_replacements | proxy:read | Replacement requests on a plan, including automatic ones. |
get_proxy_replacement | proxy:read | One replacement request and its current state. |
list_replaced_proxies | proxy:read | Proxies that were replaced on a plan, what replaced them and why. |
create_proxy_replacement | proxy:write | Replaces proxies on a plan by country, IP range or IP address. Supports a dry run to preview the change first. Uses replacement credits and cannot be undone. |
IP authorization
| Tool | Scope | Description |
|---|---|---|
list_ip_authorizations | proxy:read | IP addresses authorized on a plan, with when each was added and last used. |
get_ip_authorization | proxy:read | One IP authorization. |
create_ip_authorization | proxy:write | Authorizes a public IPv4 address on a plan. Takes effect immediately. |
delete_ip_authorization | proxy:write | Removes an IP authorization. Connections from that IP stop working right away. |
Notifications
| Tool | Scope | Description |
|---|---|---|
list_notifications | account:read | Your dashboard notifications, such as bandwidth alerts and renewal reminders. |
get_notification | account:read | One notification in detail. |
Products & pricing
| Tool | Scope | Description |
|---|---|---|
list_proxy_catalog | catalog:read | The proxy products Webshare sells. |
get_customize_options | catalog:read | Configuration limits and live country availability for a product. |
get_pricing | catalog:read | A price quote for a proxy configuration, monthly and yearly. |
Disconnect an app
Every app you allow shows up on the Connected Apps (opens in a new tab) page of your dashboard, with the date you allowed it and its read and write access.
To remove an app's access, click Disconnect next to it and confirm. The app loses all access right away. You may be asked for your two-factor authentication code. To use the app again, connect it again.
Only the account owner can see and disconnect connected apps.