Does it work on n8n Cloud and on self-hosted n8n?

Yes. The MCP Client Tool and MCP Client nodes are built into n8n, and our server is reachable over HTTPS from both. The difference is proxy authentication in HTTP Request nodes: on n8n Cloud, use username/password authentication, because its outbound IP addresses are shared by many instances.

Do I need an AI Agent to use the MCP server in n8n?

No. The MCP Client node calls one tool as a regular workflow step, with no chat model. Use it for scheduled reports and alerts; use the MCP Client Tool node with an AI Agent when the request varies and the model should choose the tools.

Is the API key included when I export or share a workflow?

No. The key stays in the n8n credential. An exported workflow JSON includes the credential’s name and ID, so keep the key out of the name. If a key may have leaked, revoke it in the Dashboard under Settings → API keys and create a new one.

Can an n8n agent buy proxies without approval?

Only if its key includes the wallet:spend scope, and only up to your account balance. Without that scope, paid calls are rejected on our end. With it, put paid tools in a separate MCP Client Tool node behind a human review step.

Does the MCP server cost extra?

No. The MCP server and the REST API are included with every PapaProxy.net account. You pay only for the proxies and add-ons you order. The chat model behind an AI Agent is billed by its provider; the MCP Client node doesn’t use one.

MCP integration

How to connect the PapaProxy.net MCP server in n8n

In n8n, the PapaProxy.net MCP server works in two ways. An AI Agent can use its 56 tools to answer questions and act on your proxy account, and a regular workflow step can call a single tool on a schedule with no model involved. Both use the same endpoint, one API key, and one n8n credential. This guide also shows how to route HTTP Request nodes through your proxies.

Create an API key Choose a node Download this guide as .md for your agent

Which node to use
Key and credential
AI Agent
Human review
Steps without a model
Workflow recipes
Proxies in HTTP Request
Troubleshooting
FAQ

Which node to use

n8n has two built-in MCP nodes, and they solve different problems. Pick one by asking who decides which tool runs: the model or you.

Node	Who picks the tool	Best for
MCP Client Tool, attached to the Tool input of an AI Agent	The model, based on the request	Chat bots and requests in plain English: “What’s failing on my proxies today?” Every run uses model tokens.
MCP Client, a regular workflow step	You, when you build the workflow	Scheduled reports and alerts. The same tool runs with the same parameters every time, and no model is involved.
HTTP Request (not MCP)	You	Calling the REST API directly, or sending a workflow’s own requests through your proxies (see below).

Analytics tools such as get_usage_overview and get_diagnostics are available only over MCP. To use them in a scheduled workflow without an agent, use the MCP Client node.

Step 1. Create a key and an n8n credential

Workflows run unattended, often for months, so give each workflow its own key. If one workflow misbehaves, you revoke its key without touching the rest. In the Dashboard, open Settings → API keys, name the key after the workflow, and select only the scopes it needs. The full key is shown once, right after creation.

Workflow	Scopes
Usage and error reports	`services:read`, `usage:read`
Low-balance alert	`wallet:read`
Price-quote chat bot for your team	`catalog:read`
Whitelisting the n8n server’s IP	`services:read`, `services:write`, `customer:read`
An agent that orders and renews	the scopes above plus `wallet:read` and `wallet:spend`, with human review

Then store the key in n8n:

Open the credential form. In the MCP node you’re adding, set Authentication to Bearer Auth, then open the Credential list and choose Create new credential.
Paste the key. Paste the key itself, starting with fb_, into Bearer Token. Don’t type the word Bearer: n8n adds it to the header.
Name and save it. Give the credential a neutral name, for example “PapaProxy.net — reports”, and save it.

n8n keeps credentials separately from workflows. An exported workflow JSON includes the credential’s name and ID, but not the key, so you can share a workflow without sharing the key. Don’t put the key, or part of it, in the credential name.

Option 1. Give an AI Agent proxy tools

Start with an AI Agent node that has a chat model connected, for example after a Chat Trigger. Click + on the agent’s Tool input, search for MCP Client Tool, and fill in the fields:

MCP Client Tool

Endpoint:           https://papaproxy.net/account_new/api/v1/mcp
Server Transport:   HTTP Streamable
Authentication:     Bearer Auth
Credential:         PapaProxy.net — reports
Tools to Include:   Selected

With Tools to Include set to Selected, n8n loads the tool list from our server using your credential, and you check the tools the agent may see. Fewer tools mean a shorter tool list in every model call and fewer wrong picks. For a reporting agent, these are enough:

Tools to Include → Selected

list_services
get_service
get_usage_overview
get_usage_timeseries
get_top_destinations
get_diagnostics
get_recommendations

Tell the agent what it’s for in its system message. Amounts come back in cents, so say how to show them:

AI Agent → Options → System Message

You manage proxies on a PapaProxy.net account through the PapaProxy.net tools.
Amounts from the tools are in US cents; show them in dollars, for example $12.50.
Before any paid action, get a quote first and show it.
If a tool returns an error, quote its short code and explain it in one sentence.

Open the chat and send a request that can’t cost anything, for example “Which of my services had the most errors this week, and why?”. The execution log shows each tool the agent called and what it returned.

Human review for paid tools

n8n can pause a workflow before an AI Agent runs a specific tool and ask a person to approve or deny the call in Slack, Telegram, Microsoft Teams, Discord, Gmail, or the n8n chat. Review applies to the tools connected to the review step, so split the PapaProxy.net tools across two MCP Client Tool nodes with the same endpoint and credential:

“PapaProxy.net — read”, connected directlyRead-only tools the agent can call at any time: list_countries, quote_composite, list_services, get_service, get_usage_overview, get_diagnostics, wallet_balance. Nothing changes and nothing is charged.

“PapaProxy.net — orders”, behind human reviewTools that charge your balance or change access: order_composite, add_ips, renew_service, purchase_addon, refresh_ips, add_whitelist_ip, remove_whitelist_ip.

Add the review step. Click the AI Agent’s Tool input to open the Tools panel, find Human review, and pick the channel your team watches.
Connect the paid tools to it. Attach the “orders” MCP Client Tool node to the review step’s tool input instead of the agent’s.
Write the approval message. {{ $tool.name }} holds the node name, which is why the node needs a clear name, and {{ $tool.parameters }} shows what the agent wants to send, such as the countries, the IP count, and the term.

If the reviewer denies a call, it doesn’t run, and the agent is told it was rejected. Review is a workflow setting, though, and the real boundary is the key: a key without wallet:spend can’t pay for anything, whatever the workflow does, and a key with it can pay only from your account balance.

Option 2. Call a tool as a regular step, with no model

The MCP Client node runs one tool you choose and passes its result to the next node, like any other step. It doesn’t need an AI Agent or a chat model, so a scheduled check costs nothing in tokens and returns the same structure every time.

MCP Client

Server Transport:   HTTP Streamable
MCP Endpoint URL:   https://papaproxy.net/account_new/api/v1/mcp
Authentication:     Bearer Auth
Credential:         PapaProxy.net — reports
Tool:               get_diagnostics
Input Mode:         Manual

The Tool list loads from our server, and in Manual mode the node shows the parameters of the selected tool. Use JSON mode to pass parameters from earlier nodes with an expression. Our tools return JSON, and the node exposes it as structuredContent, so later nodes can read fields directly, for example {{ $json.structuredContent.balance_cents }} after wallet_balance.

Workflow recipes

Each recipe lists the nodes in order and the key scopes it needs. Start with a key that can only read.

Morning error digestSchedule Trigger → MCP Client → MCP Client → SlackEvery morning, call get_usage_overview for request totals and success rate, then get_diagnostics for errors by status code and category, and post both to a channel. No model needed. Scopes: services:read, usage:read.

Low-balance alertSchedule Trigger → MCP Client → If → TelegramCall wallet_balance every few hours. In the If node, check {{ $json.structuredContent.balance_cents }} is less than 2000, which is $20.00, and send a message to top up your balance before auto-renewal. Scope: wallet:read.

Price-quote bot for your teamChat Trigger → AI Agent + MCP Client ToolSelect only list_countries, get_pricing_info, and quote_composite. Colleagues ask “How much are 300 IPs in Germany for three months?” and get a live quote. With only catalog:read, the key can’t see your services or buy anything.

Whitelist a self-hosted n8n serverManual Trigger → MCP Client → MCP Clientget_my_ip returns the IP the request comes from, which for a self-hosted instance is your n8n server’s public IP. Pass it to add_whitelist_ip with your service ID, and HTTP Request nodes can use the proxies without a password. Don’t do this on n8n Cloud: see why.

Mind the request rate in loops. The limit is 60 requests per minute per account, shared by all your API keys and the MCP server. An MCP Client node inside Loop Over Items makes one call per item, so for long lists add a Wait node to the loop or ask for the data in one call where a tool allows it.

Keep big lists away from the model. list_proxy_ips returns the whole list of a service in one response. In an AI Agent, that list goes into the model’s context and costs tokens on every following step. Call it from an MCP Client node instead and process the result with Split Out or a Code node.

All 56 tools, with the scope each needs and the REST endpoint it calls, are in the API reference.

Send HTTP Request nodes through your proxies

MCP manages the proxy account. To send a workflow’s own traffic through the proxies, for example when scraping a target website, set a proxy on the HTTP Request node: click Add option, choose Proxy, and enter the proxy URL. Use the IP, the HTTP port, and the credentials from your proxy list in the Dashboard.

HTTP Request → Options → Proxy

http://LOGIN:PASSWORD@IP:PORT

Only HTTP and HTTPS proxy URLs work here. n8n ignores a URL that starts with socks5://, writes a warning to its log, and sends the request without that proxy. The node doesn’t fail, so the request goes out from the n8n server’s own IP.
Special characters in the password, such as @, :, or /, must be URL-encoded, for example @ as %40.
The node option overrides the HTTP_PROXY, HTTPS_PROXY, and ALL_PROXY environment variables for that node, so one workflow can use proxies while the rest of the instance doesn’t.

IP whitelisting or a password: depends on where n8n runs

Where n8n runs	Use	Why
Self-hosted, on your server	IP whitelisting or username/password authentication	The server’s public IP belongs to you. Add it with the recipe above, and the proxy URL needs no credentials: `http://IP:PORT`.
n8n Cloud	Username/password authentication only	n8n Cloud sends outbound requests from IP addresses that many instances share. If you whitelisted them, other n8n Cloud workflows sending requests from the same IP could use your proxies.

Troubleshooting: n8n MCP Client not working

Open the failed execution and click the MCP node: the error panel shows the message our server returned.

What you see	Cause and fix
`Missing or malformed Authorization header`	Authentication is set to None, or no credential is selected. Choose Bearer Auth and the PapaProxy.net credential.
`Invalid or revoked API key`	The token starts with `Bearer` , so the header ends up with the word twice; keep only the key in Bearer Token. Also check for a typo, a leftover space, or a revoked key.
The Tools to Include or Tool list is empty or shows an error	n8n loads the list from our server with your credential, so the list fails for the same reasons a call would. Fix the endpoint and credential first, then reopen the list.
Connection errors with Server Transport set to Server Sent Events	Our server uses Streamable HTTP. Choose HTTP Streamable.
The node shows an SSE Endpoint field and no transport choice	It’s the first version of the node, which connects only over SSE. Delete it and add the MCP Client Tool node again; on older n8n versions, update n8n first.
A self-hosted instance can’t connect at all	The server can’t reach `papaproxy.net` over HTTPS: check the firewall, or the `HTTPS_PROXY` and `NO_PROXY` variables if the instance runs behind a corporate proxy.
A tool call fails with a scope error	The key doesn’t have the scope the tool needs. Errors come back as text with a short code and an explanation. Create a new key with the missing scope and update the credential.
Calls start failing in the middle of a loop	The 60-requests-per-minute limit is shared by the whole account. Add a Wait node to the loop.
Target websites see the n8n server’s IP	The HTTP Request proxy URL starts with `socks5://` or has no scheme. Use `http://` and the HTTP port.

If the error comes from our server rather than the node configuration, contact support with the time of the failed execution; we’ll check it on our end.

Other MCP clients

The same endpoint and key work in other clients. There are step-by-step guides for Cursor and Claude Code, and setup for VS Code, Windsurf, Cline, Codex CLI, Gemini CLI, and Claude Desktop is on the developers page.