How to Use the Geocodio MCP in Windsurf

Q: How does Windsurf use Geocodio to handle batch geocoding?

Windsurf's Cascade agent uses the batchgeocodeaddresses tool. You just point it to a list of addresses and state your goal. Cascade plans and executes the API call to Geocodio, processing the entire list and returning coordinates without you needing to loop or script anything.

Q: Can I go from a latitude/longitude coordinate back to a street address?

Absolutely. For a single point, tell Windsurf to use the reversegeocode tool. If you have a list of coordinates, it will automatically use batchreversepins to process them all efficiently.

Let Windsurf's Cascade turn a list of addresses into a complete dataset with census and legislative info, all in one autonomous run.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers - Free for Subscribers

Connect Geocodio MCP to Windsurf

Create your Vinkius account to connect Geocodio to Windsurf and route execution through our secure gateway. The platform manages server hosting, runtime updates, and security layers. Configuration requires no manual server provisioning.

GDPR Free for Subscribers

Setup Geocodio with Windsurf

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Turn Addresses into Data

This server gives Windsurf the tools to convert raw addresses into precise coordinates and rich location data. Give Cascade a goal like "Geocode these properties and find their school districts." It will automatically chain `batch_geocode_addresses` to get the coordinates, then use `batch_enriched_geocode` to pull back the specific data you need for every single address. You don't have to prompt each step. Windsurf sees the goal, finds the tools, and executes the whole sequence. This is perfect for building property reports or mapping customer locations without writing a line of code. Just drop a CSV file in your editor and tell Cascade what you want to know.

From Coordinates to Context with Windsurf

If you start with GPS coordinates, you can work backwards. Use `reverse_geocode` to find the street address for a single point, or feed a whole list to `batch_reverse_pins` to process them all at once. Cascade can take a list of coordinates and turn it into a list of formatted addresses. The real power is adding context. Ask Cascade to "find the congressional districts for these GPS points," and it will use `batch_enriched_reverse` to look up the addresses and append the district data automatically. You can find out what data is available by asking it to run `list_schema_fields` first.

Build Location-Aware Workflows

This Geocodio MCP Server isn't just for one-off lookups. You can integrate it into bigger autonomous workflows inside Windsurf. For example, have Cascade monitor a file for new addresses, automatically geocode them, and then save the results to a new file with census tract information. Because Cascade handles the planning, you can build surprisingly complex chains. It can read a list, geocode it, filter the results based on timezone, and then pass the filtered list to another tool for analysis. It connects the dots for you.

Setup guide

Set up Geocodio MCP in Windsurf

Prerequisites

Windsurf IDE installed (macOS, Windows, or Linux)
Active Vinkius subscription with a valid endpoint token

1

Open MCP configuration

Click the Cascade assistant icon in the sidebar, then click the hammer icon (🔨) at the top of the panel. Select "Configure" to open ~/.codeium/windsurf/mcp_config.json.
2

Add the Geocodio MCP

Paste the JSON snippet shown on the right into the mcpServers object. Replace [YOUR_TOKEN_HERE] with your endpoint token from cloud.vinkius.com.
3

Refresh MCPs

Go back to the hammer icon (🔨) in Cascade and click "Refresh". Windsurf will detect the new server. No full restart is needed — the connection is hot-reloaded.
4

Verify in Cascade

Start a new Cascade conversation and ask something like "Show my Geocodio payment history." If connected, Cascade will call the Geocodio tools directly. You will see a green dot next to the server name in the MCP panel.

mcp_config.json

{
  "mcpServers": {
    "geocodio-mcp": {
      "url": "https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp"
    }
  }
}

Get your connection token →

Independent Platform Disclaimer: Vinkius is an independent platform and is not affiliated with, endorsed by, sponsored by, verified by, or otherwise authorized by Geocodio. All third-party trademarks, logos, and brand names are the property of their respective owners. Their use on this website is strictly for informational purposes to identify service compatibility and interoperability.

Why Choose Vinkius

Vinkius connects your tools to AI with real-time monitoring and automatic cost savings — all from one dashboard.

Connect Geocodio now

Real-time monitoring

Live

visibility into every interaction

Connect your favorite tools to your AI and see exactly what's happening — every request, every response, in real time.

Built-in savings

60%

lower AI costs

Vinkius compresses data between your apps and your AI automatically. Lower bills every month — no configuration required.

Single dashboard

One

place for every integration

Every tool your AI connects to, managed from a single screen. One account, complete control.

Common questions about Geocodio MCP in Windsurf

Windsurf's Cascade agent uses the `batch_geocode_addresses` tool. You just point it to a list of addresses and state your goal. Cascade plans and executes the API call to Geocodio, processing the entire list and returning coordinates without you needing to loop or script anything.

Yes. Give Cascade a list of addresses and ask for census data. It will use the `batch_enriched_geocode` tool to fetch coordinates and the requested census information—like tract and block codes—from Geocodio for each address in a single operation.

Just ask Windsurf to "list all available schema fields from Geocodio." It will run the `list_schema_fields` tool and show you a complete list of all the data points you can request, from timezones to school districts and congressional boundaries.

Absolutely. For a single point, tell Windsurf to use the `reverse_geocode` tool. If you have a list of coordinates, it will automatically use `batch_reverse_pins` to process them all efficiently.

Yes, the Geocodio server processes the street addresses and coordinates you send. Vinkius secures the connection with an ephemeral, zero-trust environment for each request. The data is only used to get your geocoding results and isn't stored long-term.

Use it with your favorite AI tools

Connect this server to Cursor, Claude, VS Code, and more.

OpenAI Agents SDK sdk-python

Google ADK sdk-python

Pydantic AI sdk-python

Vercel AI SDK sdk-typescript