---
title: "Protect an MCP server at your proxy | FoxAuth"
description: "Let your Caddy, Traefik or nginx proxy ask FoxAuth to check every token, and the scopes each tool needs, so your MCP server needs no auth code."
canonical: "https://foxauth.dev/docs/get-started/protect-an-mcp-server-at-your-proxy/"
lastmod: "2026-11-12T15:42:54+03:00"
---
Protect an MCP server at your proxy

An MCP server that checks tokens itself needs code for it. It fetches the project’s keys, checks each token, answers
401 with the right header, and publishes a document that tells agents where to sign in. Protect your MCP server
with OAuth walks through that code. This page shows a way to skip it.

Your reverse proxy (Caddy, Traefik or nginx) stands in front of the MCP server. Before each request reaches the
server, the proxy asks your FoxAuth project to check it. The project checks the token, and the scopes the called tool
needs. Only a request that passes reaches your MCP server. A scope is one named permission a token carries, such as
files:read.

This page takes about ten minutes if your proxy already serves the MCP server.

What you need first

A running instance with an administrator account (Create the first
administrator) and a project of your own
(Register your first client walks that).
The MCP server must be served over https by a proxy you can configure. Agent
hosts must be able to identify themselves to the project: see Let an agent
host identify
itself.

What the proxy checksSection titled “What the proxy checks”

For every request, the proxy calls the project’s check, at an address such as
https://auth.example.com/acme/verify/api/<checkId>. The check reads the token from the request’s
Authorization: Bearer header. It accepts the token only when everything an MCP server would check holds:

the project’s own keys signed it;

the project issued it;

it was issued for this MCP server and no other (its audience);

it has not expired, and its start time has passed;

it is an access token, not an ID token.

The project can also issue opaque tokens: a random string with nothing readable inside. The check looks such a token
up in the project and accepts it only while it is unexpired and not revoked.

A request with no token, or with a token that fails, gets 401. Its WWW-Authenticate header names a document that
tells the agent where to sign in. That document is the protected resource metadata (RFC 9728), and the project serves
it for you. Your MCP server serves nothing for sign-in.

1. Declare the API with “Your proxy”Section titled “1. Declare the API with “Your proxy””

Open your project and choose its APIs tab, then New resource.

Fill in:

Resource identifier: the address agents call, such as https://mcp.example.com/mcp. It must be an https
address, because the check compares its host with the host the proxy reports.

Name: what people see on the consent page.

Scopes: the permissions your tools tell apart, such as files:read, files:write and files:delete.

Who checks tokens?: choose Your proxy.

Look at the token settings. A revoked self-contained token keeps working at the proxy until it expires (see
Revoked tokens below). So choose Opaque, or keep the lifetime short.

You can switch an existing API to Your proxy on its Settings tab too. Tokens issued before the switch keep working
until they expire.

2. Configure your proxySection titled “2. Configure your proxy”

Open the API’s page from the project’s APIs tab. Its Connect tab shows the check’s address, the metadata address and the configuration for
your proxy, with your addresses filled in. Copy it from there. The examples below are the same text, built by the
same code, for an MCP server at https://mcp.example.com/mcp in a project at https://auth.example.com/acme. Your
API’s check id takes the place of <checkId>.

Each configuration does three things:

It sends every request to the check first, with the request’s original method and host.

It removes any X-Auth-* header the client sent, so nobody can pretend to be someone else.

It passes the request to your MCP server with the headers the check answered. The Authorization header goes on
untouched.

The MCP server itself is assumed to listen on 127.0.0.1:8080. Replace that with its real address.

CaddySection titled “Caddy”

Caddyfile

mcp.example.com {

route {

request_header -X-Auth-*

forward_auth https://auth.example.com {

uri /acme/verify/api/<checkId>

header_up Host {upstream_hostport}

copy_headers X-Auth-Subject X-Auth-Client X-Auth-Scope X-Auth-Reason

}

reverse_proxy 127.0.0.1:8080

}

}

The route block keeps the order as written. Without it, Caddy would remove the X-Auth-* headers after the check
had set them. When the check refuses, forward_auth passes its answer back to the client, headers included.

TraefikSection titled “Traefik”

Traefik dynamic configuration

http:

middlewares:

foxauth:

forwardAuth:

address: "https://auth.example.com/acme/verify/api/<checkId>"

trustForwardHeader: false

authResponseHeadersRegex: "^X-Auth-"

routers:

api:

rule: "Host(`mcp.example.com`)"

entryPoints:

- websecure

middlewares:

- foxauth

service: api

tls: {}

services:

api:

loadBalancer:

servers:

- url: "http://127.0.0.1:8080"

This is a dynamic configuration for the file provider. authResponseHeadersRegex removes every X-Auth-* header
the client sent and copies the ones the check answered. When the check refuses, Traefik passes its whole answer back.

nginxSection titled “nginx”

nginx configuration

map $status $foxauth_scope_challenge {

403 $foxauth_www_authenticate;

default "";

}

server {

listen 443 ssl;

server_name mcp.example.com;

# ssl_certificate and ssl_certificate_key for mcp.example.com

location / {

auth_request /_foxauth_check;

auth_request_set $foxauth_x_auth_subject $upstream_http_x_auth_subject;

auth_request_set $foxauth_x_auth_client $upstream_http_x_auth_client;

auth_request_set $foxauth_x_auth_scope $upstream_http_x_auth_scope;

auth_request_set $foxauth_x_auth_reason $upstream_http_x_auth_reason;

auth_request_set $foxauth_www_authenticate $upstream_http_www_authenticate;

add_header WWW-Authenticate $foxauth_scope_challenge always;

proxy_set_header X-Auth-Subject $foxauth_x_auth_subject;

proxy_set_header X-Auth-Client $foxauth_x_auth_client;

proxy_set_header X-Auth-Scope $foxauth_x_auth_scope;

proxy_set_header X-Auth-Reason $foxauth_x_auth_reason;

proxy_set_header Host $host;

proxy_pass http://127.0.0.1:8080;

}

location = /_foxauth_check {

internal;

proxy_pass https://auth.example.com/acme/verify/api/<checkId>;

proxy_set_header X-Forwarded-Host $host;

proxy_set_header X-Forwarded-Uri $request_uri;

proxy_set_header X-Forwarded-Method $request_method;

proxy_set_header Host auth.example.com;

proxy_ssl_server_name on;

proxy_pass_request_body off;

proxy_set_header Content-Length "";

}

}

nginx’s auth_request understands only three answers: allowed, 401 and 403. On a 401, nginx passes the
check’s WWW-Authenticate header to the client by itself. On a 403 it does not, so the map at the top adds it
back. That header is how a client learns which scopes a tool needs. The map belongs in the http context, which a
file in conf.d already is. Add your certificate lines where the comment says.

3. Keep the MCP server reachable only through your proxySection titled “3. Keep the MCP server reachable only through your proxy”

The check protects only the requests that pass through your proxy. A request that reaches the MCP server another way
skips it, and the server would trust any X-Auth-* header it carried.

So make the MCP server listen only where the proxy can reach it: on 127.0.0.1, on a private network, or behind a
firewall rule that admits only the proxy.

4. What your MCP server receivesSection titled “4. What your MCP server receives”

When a request is let through, the proxy adds these headers:

Header
What it holds

X-Auth-Subject
Who the token speaks for: the token’s sub. For a machine token, it is the client’s id.

X-Auth-Client
The id of the client that holds the token, such as the agent host.

X-Auth-Scope
The token’s scopes, separated by spaces.

X-Auth-Reason
A short code for the decision: allowed, or preflight for a browser’s CORS check, which carries no token and gets the others empty.

Authorization
The original token, untouched. A server that trades it for the person’s tokens at another service needs it. It may also check it itself.

5. Say which scopes each tool needsSection titled “5. Say which scopes each tool needs”

Without a tools table, any valid token may call any tool. To set one, open the API’s page and its Access tab.

An MCP client following the MCP specification of 2026-07-28 names what it does in two headers: Mcp-Method (such as
tools/call) and Mcp-Name (the tool). The check reads them, so the table can say which scopes each tool needs:

Tool
Scopes it needs

search_files
files:read

delete_file
files:write, files:delete

You pick the scopes from the API’s own scopes. With this table:

A call to delete_file with a token that holds only files:write gets 403. Its WWW-Authenticate header says
error="insufficient_scope" and lists every scope the tool needs, files:write files:delete. A client can then ask
for exactly those.

Listing the tools (tools/list) needs only a valid token, so a client can always see what it may call.

A tools/call that names no tool is refused.

Tool names match exactly: Delete_File is not delete_file.

Two choices sit under the table:

Any other tool: a tool the table does not list is refused, or needs only a valid token. Refused is the default.

Clients too old to say which tool they call: a client that sends no Mcp-Method, or speaks a protocol older
than 2026-07-28, is refused by default. You can let them in, but then they can call any tool. Once a tool has
conditions of its own, you cannot: see Old apps are refused.

What the table does not coverSection titled “What the table does not cover”

Reading a resource (resources/read) and getting a prompt (prompts/get) need only a valid token. The table
names tools only.

The proxy sees the headers, not the body. Your MCP server must still refuse a request whose Mcp-Name header and
body name different tools. The MCP specification asks servers to do this, and it is why older clients are refused
by default: their servers do not compare the two.

Limits to knowSection titled “Limits to know”

A revoked token works until it expiresSection titled “A revoked token works until it expires”

A self-contained token carries everything the check needs, so the check does not ask the project whether it was
revoked. Asking would put a database read on every call. A revoked self-contained token therefore keeps working at
the proxy until it expires. The default lifetime is fifteen minutes. If you need revocation to work at once, issue
opaque tokens: the check looks each one up, so a revoked token is refused on the next request.

Tokens bound to a key are refusedSection titled “Tokens bound to a key are refused”

Some tokens work only together with a key the client holds, through DPoP or a client certificate (mTLS). The proof
of the key belongs to the request the client sent to your MCP server, and the proxy passes on only headers. So the
check cannot prove the key, and it refuses such tokens with 401 and the reason bound_token_unsupported. It does
not accept them as plain tokens.

Refusals carry no CORS headersSection titled “Refusals carry no CORS headers”

A browser lets a page on another site read an answer only when the answer carries CORS headers. The check’s 401
and 403 carry none. So a browser-based MCP client cannot read WWW-Authenticate from a refusal, unless your proxy
adds CORS headers to errors. A browser’s CORS check itself (OPTIONS with Access-Control-Request-Method) carries
no token and is let through, so your MCP server answers it.

Anyone who can sign in to the project can get a tokenSection titled “Anyone who can sign in to the project can get a token”

Anyone who can sign in to the project can get a token for this API. To limit who may call it, add conditions to the
API, as Add conditions at your proxy shows, or to one of its
tools, as Conditions on one tool shows. You can also limit who can sign in to the project.

6. Check that it worksSection titled “6. Check that it works”

Call your MCP server with no token:

Terminal window

curl -i https://mcp.example.com/mcp -X POST \

-H 'content-type: application/json' \

-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

You should get 401 with a WWW-Authenticate: Bearer resource_metadata="…" header. If you get your MCP
server’s own answer, the request did not pass through the check.

Open the address from resource_metadata. Its resource is your API’s identifier, and authorization_servers
names your project.

Point your agent host at your MCP server. It reads that document, signs the person in at the project, and comes
back with a token. The same call now reaches your server, with the X-Auth-* headers.

There is nothing to switch on, and it is on every plan.

To let only some groups call the API, or only from your network or in your hours, see Add conditions at your
proxy. To do that for one tool only, read on.

Conditions on one toolSection titled “Conditions on one tool”

The API’s own conditions hold for every tool. Sometimes one tool needs more. Say only the Ops group may call
delete_files, or export_billing may be called only from the office network in working hours. Every other tool
stays as open as before.

On the API’s Access tab, in the tools table, choose Add conditions under the tool. A tool takes three
kinds of condition, with the same controls as the API’s own:

Groups: the person is in one of the groups you choose.

From where: the address is in your ranges, or not in them. It can also keep out what FoxTrust’s network facts
name, such as Tor. Your proxy must pass people’s addresses, as From
where shows.

When: the days and the hours, in the API’s one time zone.

A tool holds at most four conditions. It takes no attribute and no new sign-in. A code or a recent sign-in is set for
the whole API: see Ask for a code or a recent sign-in.

How a tool’s conditions add upSection titled “How a tool’s conditions add up”

A tool’s conditions are added to the API’s own. They never replace them and never loosen them. If the API lets in
only Staff and delete_files only Ops, a person must be in both groups to call delete_files.

Under the tool, the editor shows the API’s conditions as coming from the API. You cannot remove them there.

The check decides in this order: the API’s conditions, the API’s sign-in requirement, the MCP headers, the tool’s
scopes, and then the tool’s conditions.

A token without the tool’s scopes gets insufficient_scope, as before. It learns nothing about the tool’s
conditions.

A tool can have conditions and no scope. Every tool in the table needs at least one scope or one condition.

Only a tools/call that names the tool is judged on its conditions. Listing the tools and starting a session are
not.

Removing a tool’s condition, or loosening it, lets more calls through. So the console lists what loosens and asks you
to confirm before it saves. Adding a condition saves at once.

What a refused call looks likeSection titled “What a refused call looks like”

A call that does not meet the tool’s conditions gets 403. X-Auth-Reason says why:

Reason
What it means

not_in_group
The person is not in the tool’s groups, or not in the API’s.

not_from_network
The address is not one the conditions let in, or your proxy passed none it can trust.

network_facts_unknown
Network facts are off or older than 26 hours, so a condition that needs them refuses.

outside_hours
The call came outside the hours, in the API’s time zone.

no_person
The token stands for no person, such as a token an app got for itself.

cannot_sign_in
The person is locked or deactivated.

A refused call is never a 401, and the person is never asked to sign in again. A new sign-in does not put anyone in
a group or in the office. The answer names neither the tool nor its conditions.

What a tool condition cannot stopSection titled “What a tool condition cannot stop”

Your proxy sees the request’s headers, not its body. The tool’s name comes from the Mcp-Name header the app sends.

A tool condition stops an app that names the tool it calls honestly. A stolen token in an app that lies about the tool
is stopped only by your MCP server checking the headers against the body, which MCP 2026-07-28 servers must do. To keep
someone out of the whole API, use the API’s own conditions or its sign-in requirement.

So a tool condition guards against an agent’s mistake. It is not a lock against someone who holds a stolen token.

Old apps are refusedSection titled “Old apps are refused”

An app too old to say which tool it calls cannot be held to one tool’s conditions. That is an app that sends no
Mcp-Method header, or speaks an MCP protocol older than 2026-07-28. So once any tool has conditions, Clients too
old to say which tool they call must be Refuse them. The console turns Let them in off, and a save that asks
for it is refused with 422. Today many apps are such apps: the table below says
which.

A new or renamed tool on your MCP server is not in the table yet. It gets the Any other tool answer until you add
it.

Check accessSection titled “Check access”

The API’s Access tab ends with a Check access card. Choose a person, or No person: an app acting for itself. Then
choose the scopes the app’s token holds, the tool it calls or another request, an address and a time. When the API
requires a code or a recent sign-in, also say whether the sign-in had a code and when it happened.

The card answers Allowed, Refused or Asked to sign in again, with the reason in plain words. It answers for
the saved table and for the one you are editing. When it lacks something it needs, it answers Not known and names
what is missing. It runs the same decision as the check at your proxy, in your browser. No server decides for
it, and nothing is written to the audit trail. When a condition needs network facts, the card looks the address up in
your server’s own copy.

An agent sets a tool’s conditions with resource_update, as conditions on a row of tools. Conditions on one tool
are free on every plan.

Ask for a code or a recent sign-inSection titled “Ask for a code or a recent sign-in”

A token says that someone signed in to the project. It does not say how. So a stolen password is enough to connect an
agent to your MCP server. Two settings on the API’s Access tab change that. Open the project’s APIs tab, then the API, then
Access:

Require a code from an authenticator app. A token for this API is issued only after a sign-in in which the
person typed a code from an authenticator app, such as Google Authenticator.

Ask to sign in again every. Choose every day, every 7 days, every 14 days, or Custom: a whole number of
hours or days, from 1 hour to 14 days. The person behind a token must have signed in no longer ago than that.

You can set one, the other or both. They work on any API, whoever checks its tokens: your proxy or the API’s own
server. An agent can set them through the admin MCP server, with requireCode and signInEveryMinutes in
resource_declare and resource_update. They are free on every plan.

What FoxAuth doesSection titled “What FoxAuth does”

There is a standard answer an API sends to ask for a stronger or more recent sign-in: 401 with
error="insufficient_user_authentication" (RFC 9470). On 2026-11-12, no MCP client we looked at understood it. But
every client asks for a new token when it gets a 401. FoxAuth issues that token, so it makes the requirement hold
itself:

When a person signs in to get a token for this API, FoxAuth asks for the code, whatever the client asked for. When
the person’s sign-in is older than allowed, FoxAuth asks them to sign in again.

The sign-in page has a line that names the API, such as “Files asks for a code from an authenticator app to
connect.” or “Files asks you to sign in again every day to stay connected.”

A person with no authenticator app can set one up inside the same sign-in, if the project lets people set one up
themselves.

Every way of getting a token for a person checks the requirement: the authorization code, the device flow, CIBA
and the refresh token.

A renewal with a refresh token that would not meet the requirement is refused with invalid_grant. The refresh
token is not spent. The client then starts a new sign-in, and the person’s other connections keep working.

At your proxy, the check judges each token by the sign-in it came from. A token that falls short gets 401 with
WWW-Authenticate: Bearer error="insufficient_user_authentication" and acr_values="…" or max_age="…". This is
the standard challenge, for the clients that learn it. X-Auth-Reason is code_required or sign_in_not_fresh.

Token introspection returns acr and auth_time, so an API that checks its own tokens can apply the same rule.

An API that checks its own tokens decides about the tokens it already holds. A token issued before you turned the
requirement on keeps working there until it expires, unless your server checks acr and auth_time in the token.
Its renewal is refused either way.

Who cannot connectSection titled “Who cannot connect”

Some tokens stand for no sign-in that FoxAuth saw. No new sign-in can fix them, so they are refused, not asked to sign
in again:

An app that acts for no one. An app that gets tokens for itself, with the client credentials grant, gets no
token for this API. At your proxy, such a token gets 403.

A sign-in by assertion. A token from the JWT bearer grant, identity assertions or ID-JAG is refused too. The
person signed in somewhere else, and FoxAuth cannot tell how.

People who sign in through a provider, such as Google or your company’s identity provider, are a third case. They
cannot type a code at FoxAuth. So when the API requires a code, the sign-in page tells them they cannot connect this
way. When the API only asks them to sign in again, FoxAuth sends them to the provider for a new sign-in. The provider
decides how to do that, and FoxAuth cannot confirm that they signed in again.

Before you save: whom it affectsSection titled “Before you save: whom it affects”

Turning a requirement on, or shortening the time, first shows you whom it affects:

how many of the people who can reach the API have no authenticator app;

how many sign in only through a provider;

how many have a live connection that includes this API.

It also names the apps that can no longer connect: those that act for no one, and those that sign in by assertion.
The counts start with “Up to”, because FoxAuth does not record who uses each API. You confirm the change with these
numbers. An agent gets the same numbers: the first call answers 409 confirmationRequired, and the agent repeats
it with confirm: true.

If you upgrade an instance to this release, run bun run db:migrate first. After that, an older release refuses to
start against the database, so it cannot issue tokens that skip the code.

What your people see in each appSection titled “What your people see in each app”

FoxAuth refuses the old token or its renewal, and asks at the next sign-in. What a person sees in between depends on
the app they use. The last column says whether the app names the tool it calls, as MCP 2026-07-28 asks. An app that
does not is refused by an API whose tools have conditions of their own. The table comes
from each app’s code, documentation and issue tracker, as we read them on 2026-11-12. We have not yet tried each app
live. Try it with the apps your people use before you rely on it.

App
What the person sees
What they do
Says which tool it calls (MCP 2026-07-28)

Claude Code
It renews the token and tries once more. Then it marks the server as needing authentication.
Run /mcp, choose the server, then Re-authenticate. The call does not carry on by itself, so ask again.
Yes

claude.ai, Claude Desktop
A Connect card and a sign-in window. This is documented for an invalid token. We have not yet seen it for this challenge.
Choose Connect and sign in.
Not checked

ChatGPT
Perhaps only an error.
Reconnect the connector in ChatGPT’s settings.
Not checked

Codex
It may try the refused renewal again and again.
Reconnect the server.
No

VS Code (GitHub Copilot)
A sign-in window. Several calls at once can open several windows.
Sign in in one window. A code typed again in another says “This code was just used. Wait for the next one.”
No

Cursor, Zed, Gemini CLI
The server is marked as needing authentication.
Re-authenticate the server by hand.
No

Goose, from version 1.48.0, also names the tool it calls.

If an app does not carry on after the new sign-in, ask it to try again.

Try itSection titled “Try it”

Declare an MCP server as in step 1 and configure your proxy, or take one you already have.

Open its Access tab and turn on Require a code from an authenticator app. Read whom it affects, and
save.

Connect your MCP client to the server. The sign-in page names the API and asks for a code after the password. If
you have no authenticator app, set one up there.

Call a tool. It works.

On the same tab, set Ask to sign in again every to Custom, 1 hour, and save.

An hour later, call a tool again. The next renewal is refused, and your client asks you to sign in again, or does
what the table above says for it.

If the app does not carry on after the new sign-in, ask it to try again.

Tip

A web app people open in a browser, with no sign-in of its own, goes behind
the proxy differently. See Put sign-in in front of a web
app.

PreviousPut sign-in in front of a web appNextAdd conditions at your proxy
