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 the proxy checks
Section 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 anhttpsaddress, 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:writeandfiles:delete. - Who checks tokens?: choose Your proxy.
- Resource identifier: the address agents call, such as
- 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 proxy
Section 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
Authorizationheader goes on untouched.
The MCP server itself is assumed to listen on 127.0.0.1:8080. Replace that with its real address.
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.
Traefik
Section titled “Traefik”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.
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 proxy
Section 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 receives
Section 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 needs
Section 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_filewith a token that holds onlyfiles:writegets403. ItsWWW-Authenticateheader sayserror="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/callthat names no tool is refused. - Tool names match exactly:
Delete_Fileis notdelete_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 cover
Section 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-Nameheader 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 know
Section titled “Limits to know”A revoked token works until it expires
Section 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 refused
Section 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 headers
Section 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 token
Section 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 works
Section 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
401with aWWW-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. Itsresourceis your API’s identifier, andauthorization_serversnames 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 tool
Section 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 up
Section 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_filesonly Ops, a person must be in both groups to calldelete_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/callthat 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 like
Section 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 stop
Section 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 refused
Section 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 access
Section 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-in
Section 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 does
Section 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
401withWWW-Authenticate: Bearer error="insufficient_user_authentication"andacr_values="…"ormax_age="…". This is the standard challenge, for the clients that learn it.X-Auth-Reasoniscode_requiredorsign_in_not_fresh. - Token introspection returns
acrandauth_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 connect
Section 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 affects
Section 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 app
Section 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 it
Section 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.