Use Shellroute from shell-capable coding agents

Coding agents that can run shell commands can use shellroute run <country> -- <command> directly. No MCP server or custom SDK is required for the workflows below.

Requirements

The agent needs:

• — shell access
• — a stored Shellroute login or SHELLROUTE_API_KEY
• — the country code to route through

Common workflows

1. Check the request country

shellroute run US -- curl -sS https://ipinfo.io/country

Works for shell-capable agents that can execute local commands.

2. Capture a country-specific API response

shellroute run DE -- curl -sSI https://example.com/api/endpoint

Keep the URL, method, headers, cookies, and other request inputs fixed when comparing countries. That makes the network route the variable you are testing.

3. Compare several countries in one script

for country in US DE GB JP; do
  echo "=== $country ==="
  shellroute run --no-stat "$country" -- \
    curl -sS https://store.google.com/ -o /dev/null -w '%{redirect_url}\n'
done

Each iteration starts and closes its own Shellroute session. --no-stat suppresses the session summary so the command output is easier to compare.

4. Run a Python request through another country

shellroute run US -- python3 -c "import requests; print(requests.get('https://ipinfo.io/json').json()['country'])"

Python Requests respects the proxy environment variables used by this workflow, so the script does not need proxy-specific code.

5. Use non-interactive auth in CI or agent environments

export SHELLROUTE_API_KEY=pk_...
shellroute run US -- pytest tests/geo/

Get the key with shellroute reveal-key from any machine where you have logged in. Store it as a CI or agent secret rather than hard-coding it into scripts or prompts.

Where direct CLI is enough

For these workflows, shellroute run <country> -- <command> is the complete interface. The agent can invoke the same commands a developer would run in a terminal, while the rest of the machine keeps its normal connection.

A separate MCP layer would add another integration surface without solving a demonstrated limitation in these cases.

Limitations

• Each shellroute run invocation starts a separate session.
• Only HTTP and HTTPS traffic is routed. DNS, raw TCP, UDP, and ping do not go through the proxy.
• Browser automation tools such as Playwright and Puppeteer need explicit browser proxy configuration rather than relying only on proxy environment variables. See the Playwright IP geolocation recipe.
• Direct shellroute run is the tested path; interactive mode was not needed in these recipes.

When would MCP add value?

Consider an MCP layer only when a real agent workflow needs something the direct CLI does not provide, such as:

• — keeping one session open across multiple commands
• — rotating an IP within a longer-lived session
• — querying session state programmatically

None are documented by the current experiment evidence yet, so the current recommendation is to keep the integration direct and shell-native.