Skip to content

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.

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. Open your project and choose its APIs tab, then New resource.
  2. 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.
  3. 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.

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.

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.

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.

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 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.

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.

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.
  • 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.

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.

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.

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.

  1. 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.

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

  3. 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.

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.

  • 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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

  1. Declare an MCP server as in step 1 and configure your proxy, or take one you already have.
  2. Open its Access tab and turn on Require a code from an authenticator app. Read whom it affects, and save.
  3. 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.
  4. Call a tool. It works.
  5. On the same tab, set Ask to sign in again every to Custom, 1 hour, and save.
  6. 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.
  7. If the app does not carry on after the new sign-in, ask it to try again.