Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@floppydata-mcp fetch the HTML of https://example.com"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Floppydata MCP lets agents use the Floppydata Client API v2 directly from an MCP-compatible client.
It is intentionally small: install it with npx, provide FLOPPYDATA_API_KEY, and the server talks to https://api.floppydata.net.
Create a Client API key in the Floppydata dashboard:
https://app.floppydata.com/api-keys
Add this server to your MCP client:
{
"mcpServers": {
"floppydata": {
"command": "npx",
"args": ["-y", "@floppydata/mcp"],
"env": {
"FLOPPYDATA_API_KEY": "YOUR_API_KEY"
}
}
}
}That is the whole setup. There is no hosted service, no extra CLI, and no base URL configuration.
Related MCP server: Scout MCP Server
fetch_web_dataFetch a public page through Web Data.
Useful when an agent needs page HTML and the target site should be fetched through Floppydata infrastructure.
Required input:
{
"url": "https://example.com"
}Optional inputs: countryCode, city, difficulty, cacheMaxAgeDays.
create_rotating_proxy_connectionBuild one rotating proxy connection.
The most important value in the response is:
connection.connectionStringExample input:
{
"type": "residential",
"country": "US",
"city": "New York",
"rotation": 15,
"protocol": "http"
}list_rotating_proxy_locationsList available rotating proxy countries, cities, and states for a proxy type.
Example input:
{
"type": "residential"
}check_proxyCheck the exit IP and location for a proxy.
Example input:
{
"connectionString": "http://USERNAME:PASSWORD@geo.g-w.info:10080"
}The response shape is:
{
"ip": "123.45.67.89",
"location": {
"countryCode": "US",
"country": "United States",
"state": "California",
"city": "San Francisco"
}
}list_static_proxiesList static proxies on the account.
Use items[n].connection.connectionString as the copy-paste proxy URL.
get_account_balancesCheck account balances across Web Data, rotating proxy traffic, and static proxies.
Optional input:
{
"product": "proxy-rotating"
}Allowed products: web-data, proxy-rotating, proxy-static.
get_account_usageCheck account usage rollups.
Responses include:
yesterday
last7Days
last30Days
optional requestedRange when from or to is provided
lastUpdatedAt
Example input:
{
"product": "proxy-rotating",
"from": "2026-06-01T00:00:00Z",
"to": "2026-06-26T23:59:59Z",
"countryCode": "US",
"proxyType": "residential"
}The server reads the API key from FLOPPYDATA_API_KEY and sends it as X-Api-Key.
API keys and passwords are redacted from errors and logs. Proxy passwords are still returned in successful proxy connection responses because those credentials are the output customers need to use.
pnpm install
pnpm test
pnpm typecheck
pnpm lint
pnpm build
npm pack --dry-runCheck a proxy connection and return the exit IP and location seen through that proxy.
| Name | Required | Description | Default |
|---|---|---|---|
| host | No | Proxy host. | |
| port | No | Proxy port. | |
| password | No | Proxy password. | |
| protocol | No | Proxy protocol. Defaults to http. | |
| username | No | Proxy username. | |
| connectionString | No | Proxy URL to check, for example http://user:pass@host:10080. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states the output (exit IP and location) but fails to disclose behavioral details such as whether the proxy is actually used to make a request, any side effects, error handling, or performance implications. The description is too minimal to be transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, efficiently conveying the core purpose. There is no filler or repetition. While it could benefit from additional structure, it is concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 6 parameters with no output schema or annotations. The description only mentions the return value (exit IP and location) but not the format or behavior for different protocols (http, https, socks5). It fails to address error cases or prerequisites, leaving the agent with incomplete context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are individually described. The tool description adds no additional meaning beyond the schema—it does not explain how parameters relate (e.g., connectionString vs. host/port/username/password). Given high coverage, a 3 (baseline) is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Check' and the resource 'proxy connection', and specifies the output: 'exit IP and location'. It effectively distinguishes this tool from siblings like 'create_rotating_proxy_connection' and 'list_static_proxies', which have different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. With siblings like 'check_proxy', 'create_rotating_proxy_connection', and 'list_static_proxies', the description could have clarified the appropriate scenario (e.g., testing a specific proxy vs. managing proxy lists), but it does not.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Build one copy-paste rotating proxy connection string for a country, state, city, ASN, session, and rotation.
| Name | Required | Description | Default |
|---|---|---|---|
| asn | No | Optional target ASN. | |
| city | No | City from list_rotating_proxy_locations. Ignored when state is supplied. | |
| type | Yes | Proxy type. | |
| state | No | State or subdivision from list_rotating_proxy_locations. Wins over city. | |
| country | Yes | 2-letter country code, for example US. | |
| session | No | Optional sticky session id. | |
| protocol | No | Proxy protocol. Defaults to http. | |
| rotation | No | -1 for each request, 0 for sticky, or interval minutes. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It only states the tool 'builds' a string, but does not disclose whether the string is returned, requires authentication, or has any side effects. Minimal behavioral insight.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with key information. No fluff, but could be more structured (e.g., bullet points).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has 8 parameters and no output schema. Description is very brief; does not explain return value (presumably a string) or how rotation options work. Needs more detail for completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents parameters. The description adds the context of 'copy-paste' and lists attributes, but adds little beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Build one copy-paste rotating proxy connection string' with explicit attributes. It is specific but does not differentiate from siblings like list_rotating_proxy_locations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives, no prerequisites or exclusions mentioned. Siblings include list_rotating_proxy_locations, but no context is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a public web page through Floppydata Web Data. Use this when the agent needs the HTML of a URL.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Target page URL to fetch through Web Data. | |
| city | No | Optional exit city. | |
| difficulty | No | Optional access difficulty pool. | |
| countryCode | No | Optional 2-letter exit country code, for example US. | |
| cacheMaxAgeDays | No | Optional maximum age of cached content in days. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description does not disclose behavioral traits like rate limits, authentication needs, error handling, redirect behavior, or content size limits. For a fetch tool, critical gaps remain.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with action and usage. No irrelevant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema and description lacks details on return format, error behaviors, or limitations. With 5 parameters and no annotations, more context is needed for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%; all 5 parameters have descriptions. The tool description adds no extra meaning beyond what the schema already provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action 'Fetch', the resource 'public web page', and specifies output as 'HTML of a URL'. Distinguishes well from sibling proxy- and account-focused tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states 'Use this when the agent needs the HTML of a URL.' Provides clear context but lacks explicit when-not-to-use or alternative suggestions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get account balances for Web Data, rotating proxy traffic, and static proxies.
| Name | Required | Description | Default |
|---|---|---|---|
| product | No | Optional product filter. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It states 'Get' which implies a read-only operation, but does not disclose any potential side effects, authentication requirements, rate limits, or behavior when the optional product filter is omitted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that directly states the tool's action and scope. No filler or redundancy; every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (single optional parameter, no output schema), the description provides sufficient context for an AI agent to understand its purpose. However, it could be improved by briefly noting that no balances are returned if the filter yields no results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with 'Optional product filter.' The description adds value by explicitly listing the product types (Web Data, rotating proxy traffic, static proxies) which matches the enum values and clarifies the context of the balances.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and specifies the resource 'account balances' for three distinct product types. It immediately distinguishes itself from sibling tools like 'list_static_proxies' or 'fetch_web_data' by focusing purely on balance retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. The description implies usage for retrieving balances, but does not mention scenarios where it should or shouldn't be used, nor does it reference alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get account usage rollups. Responses include yesterday, last7Days, last30Days, optional requestedRange, and lastUpdatedAt.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | Optional end date or UTC date-time. | |
| from | No | Optional start date or UTC date-time. | |
| poolId | No | Optional pool id filter. | |
| product | No | Optional product filter. | |
| proxyType | No | Optional rotating proxy type filter. | |
| countryCode | No | Optional 2-letter country code filter. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden of behavioral disclosure. It only lists returned fields but does not mention read-only nature, authentication needs, or what happens with invalid parameters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two dense sentences effectively front-load the purpose and key response fields. Slightly more detail on parameter effects would not harm conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description partially explains return fields but omits details on 'requestedRange' behavior and how filters affect results. Adequate for simple usage but incomplete for complex queries.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all 6 parameters. The description adds no additional meaning beyond the schema for parameters, meeting the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool's action 'Get account usage rollups' and lists specific response fields. The tool name and context differentiate it from proxy management siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use vs. alternatives. The purpose is implicit from the tool name and description, but no when-not-to or prerequisite info is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List countries, cities, and states available for rotating proxy connection generation.
| Name | Required | Description | Default |
|---|---|---|---|
| type | Yes | Proxy type to list locations for. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It implies a read operation and associates locations with proxy types, but does not disclose aspects like coverage, staleness, or side effects. It is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no wasted words. Front-loaded with the verb and resource, perfectly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Simple tool with one parameter and no output schema. The description covers the basic purpose but does not specify output format (e.g., array of objects with country, city, state) or any limitations. Adequate but could be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description does not add meaning beyond the schema; it does not relate the 'type' parameter to the listed locations explicitly. No extra value added.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists countries, cities, and states for rotating proxy connection generation. The verb 'list' and resource 'locations' are specific, and it distinguishes from siblings like list_static_proxies and create_rotating_proxy_connection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like list_static_proxies or check_proxy. No mention of prerequisites, context, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List static proxies owned by the account, including each proxy connectionString.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description should disclose behaviors. It only says 'list' and 'includes connectionString' but does not mention read-only nature, rate limits, or whether all proxies are returned. The term 'owned by the account' implies filtering but is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence that conveys the essential information without any superfluous words. Highly front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless list tool with no output schema, the description states the resource and what is included (connectionString). It could mention pagination or format but is adequate for a simple list.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so 100% schema coverage. The description adds that connectionString is included, which is helpful. Baseline 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'static proxies owned by the account', specifying that it includes connectionString. It easily distinguishes from siblings like list_rotating_proxy_locations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool vs alternatives, or prerequisites. The description only states what it does, not when it's appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0check_proxycreate_rotating_proxy_connectionfetch_web_dataget_account_balancesget_account_usagelist_rotating_proxy_locationslist_static_proxiesScored across 7 tools
Each tool targets a distinct action: creating proxies, checking proxies, listing static proxies, account balances, account usage, fetching web data, and listing locations. No overlaps.
All tools use consistent snake_case verb_noun pattern (create, check, list, get, fetch). No mixing of conventions.
7 tools is well-scoped for a proxy/web data service. Not too few and not too many.
Covers core proxy and web data operations. Minor gaps like no update/delete proxy but core workflows are supported.
Stealth web browser for agents: search, fetch, click, download and type in persistent MCP sessions.
Scrape, crawl and search the web for AI agents via MCP.
Free remote MCP server for fetching public web pages through a rotating proxy pool.
Web and URL utilities over MCP: shorten URLs, screenshot pages, read page metadata, encode URLs.
