Connect agentgateway to Keycard
Put agentgateway in front of an MCP server so only people who sign in with Keycard can reach it, then take one person's access away with a policy.
agentgateway is a single entry point between MCP clients and MCP servers, and it enforces access there. In this recipe Keycard signs people in and decides who may reach the MCP server behind the gateway, so you change access in Keycard without editing the gateway config.
- MCP client Signs the person in through Keycard and gets a token for the gateway’s MCP endpoint.
- Keycard Issues the token only if policy lets that person reach the MCP server.
- agentgateway Checks the token against Keycard’s signing keys and refuses any request without a valid one.
- MCP server Receives only the requests the gateway lets through.
Prerequisites
Section titled “Prerequisites”- A Keycard organization where you have the Admin Role.
- Your Keycard issuer URL, from Settings → Connection in Keycard Console. It has the form
https://<zone-id>.keycard.cloud, and this recipe calls it<keycard-issuer-url>. - The Keycard CLI:
- agentgateway. This recipe was tested with agentgateway v1.7.0:
Terminal window curl -sL https://agentgateway.dev/install | bash - An MCP client that supports OAuth, such as Claude Code or Cursor.
- Node.js, so
npxcan run the sample MCP server. curlandjq.
This recipe assumes your organization runs the managed default-zone-policies Policy Set, which lets every signed-in person reach every Resource and lets a registered client act for them. If you run a Policy Set of your own, make sure it permits people to reach http://localhost:3000/mcp and includes default-app-delegation or a copy of it. See Access Policies.
Create a working directory for the files in this recipe:
mkdir keycard-agentgateway && cd keycard-agentgatewayRegister the MCP server in Keycard
Section titled “Register the MCP server in Keycard”-
Create the Resource
In Keycard Console, go to Resources and click Add Resource → Add Manually.
Field Value Name Everything MCP Server Identifier Credential Provider Zone Provider Click Protect Everything MCP Server. This is the sample MCP server you’ll run behind the gateway.
-
Add a scope
On the Resource’s page, find Supported scopes, type
in Add a scope, and press Enter. MCP clients read the supported scopes from the gateway’s metadata and request them when they sign in.
Run agentgateway in front of the MCP server
Section titled “Run agentgateway in front of the MCP server”The gateway’s mcpAuthentication policy connects it to Keycard. Setting issuer and jwks.url makes the gateway accept only tokens Keycard signed, setting audiences makes it accept only tokens issued for this MCP server, and resourceMetadata tells MCP clients where to sign in.
-
Write the gateway config
Create
config.yamlin your working directory:# yaml-language-server: $schema=https://agentgateway.dev/schema/configgateways:default:port: 3000routes:- backends:- mcp:targets:- name: everythingstdio:cmd: npxargs: ["-y", "@modelcontextprotocol/server-everything"]# The route serves the MCP endpoint and the protected resource metadata.matches:- path:exact: /mcp- path:exact: /.well-known/oauth-protected-resource/mcppolicies:# Browser-based MCP clients such as MCP Inspector need CORS.cors:allowOrigins: ['*']allowHeaders: [mcp-protocol-version, content-type, authorization]exposeHeaders: [Mcp-Session-Id]mcpAuthentication:mode: strictissuer: <keycard-issuer-url>audiences:- http://localhost:3000/mcpjwks:url: <keycard-issuer-url>/openidconnect/jwksresourceMetadata:resource: http://localhost:3000/mcpscopesSupported:- mcp:toolsbearerMethodsSupported:- headerReplace
<keycard-issuer-url>in both places with your issuer URL.audiencesandresourcemust match the Resource identifier exactly, including the/mcppath, because Keycard puts that identifier in theaudclaim of every token it issues for the MCP server. -
Run the gateway
Terminal window agentgateway -f config.yamlThe first request starts the MCP server through
npx, so the package takes a moment to download. The gateway reloads when the file changes, so leave it running.
Connect Claude Code
Section titled “Connect Claude Code”-
Add the gateway’s MCP endpoint
Terminal window claude mcp add --transport http everything http://localhost:3000/mcpFor Cursor, add the same URL under
mcpServersin.cursor/mcp.json. -
Sign in
Run
/mcpinside Claude Code, select everything, then Authenticate. Claude Code reads the gateway’s metadata, registers with Keycard, and opens Keycard’s sign-in page in your browser. Sign in and approve the consent screen. -
Call a tool
Ask Claude to run the
echotool. The call goes through the gateway to the MCP server.In Keycard Console, Applications lists the client Claude Code registered, and Audit Log shows a
credentials:issueevent for the connection.
Verify
Section titled “Verify”agentgateway runs in the foreground, so run these in a second terminal. Step 3 needs the Admin Role.
-
Call the gateway without a token
Terminal window curl -i -X POST http://localhost:3000/mcp \-H 'content-type: application/json' \-H 'accept: application/json, text/event-stream' \-d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}},"id":1}'The gateway refuses it before anything reaches the MCP server, and its
WWW-Authenticateheader points the client at the metadata:HTTP/1.1 401 Unauthorizedwww-authenticate: Bearer resource_metadata="http://localhost:3000/.well-known/oauth-protected-resource/mcp"{"error":"unauthorized","error_description":"JWT token required"} -
Call the gateway with a token
Create a
keycard.tomlin your working directory so the CLI knows about the Resource.<zone-id>is the first part of your issuer URL’s host name.[zone]id = "<zone-id>"[[credentials.default]]env_var = "MCP_TOKEN"resource = "http://localhost:3000/mcp"Sign in, which opens your browser if you don’t have a session, and read the token:
Terminal window keycard auth resource http://localhost:3000/mcpMCP_TOKEN="$(keycard credential read http://localhost:3000/mcp)"Send the same request with the token:
Terminal window curl -i -X POST http://localhost:3000/mcp \-H "authorization: Bearer $MCP_TOKEN" \-H 'content-type: application/json' \-H 'accept: application/json, text/event-stream' \-d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}},"id":1}'The gateway checks the token against Keycard’s signing keys and forwards the request:
HTTP/1.1 200 OKcontent-type: text/event-streammcp-session-id: f4d2e962-ae16-4aa4-9199-7db1ed05fba9event: messagedata: {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-06-18", ... ,"serverInfo":{"name":"mcp-servers/everything", ... }}} -
Take one person’s access away
The default policies permit everyone. A
forbidoverrides apermit, so you can take one person’s access away without rewriting the defaults.In Keycard Console, go to Policies (this opens Policy Sets). Open the default-zone-policies card’s menu, click Duplicate, name the copy Agentgateway Access, and click Duplicate. Create the
forbidinside the copy, so it uses the same policy schema as the set: click Add policy… → Create new policy, name it deny-mcp-access, and click Add to set. Switch the editor from Visual to Cedar and add:// Deny one user access to the MCP server behind the gatewayforbid (principal is Keycard::User,action,resource)when{principal.email == "troy.barnes@example.com" &&(resource has identifier) &&((resource.identifier) == "http://localhost:3000/mcp")};Replace
troy.barnes@example.comwith the address you signed in with and click Validate. Click Save and confirm, then click Activate.In Claude Code, run
/mcp, select everything, choose Clear authentication, then Authenticate again. Keycard refuses to issue you a token forhttp://localhost:3000/mcp, so Claude Code can’t connect.
Clean up
Section titled “Clean up”- Stop agentgateway with Ctrl+C.
- Remove the MCP server from Claude Code:
- In Keycard Console, activate default-zone-policies again, then remove the Agentgateway Access Policy Set.
- Delete the Everything MCP Server Resource, and the Claude Code client under Applications.
Limits
Section titled “Limits”- Keycard decides when it issues a token, and the gateway checks tokens locally against Keycard’s signing keys. A policy change applies to the next token, and a token issued before the change keeps working until it expires.
- This recipe decides access per MCP server. To decide per tool, add an agentgateway
mcpAuthorizationpolicy with rules on Keycard claims such asjwt.suborjwt.keycard_app_id, combined withmcp.tool.name. - The recipe runs on localhost. To move off it, register the gateway’s public URL as the Resource identifier and set
audiencesandresourceMetadata.resourceto match.
Troubleshooting
Section titled “Troubleshooting”- If a request with a token still gets
401, check thataudiencesinconfig.yamlmatches the Resource identifier exactly, including the/mcppath. - If Claude Code doesn’t open Keycard’s sign-in page, check the gateway’s metadata with
curl -s http://localhost:3000/.well-known/oauth-protected-resource/mcp | jq.authorization_serversshould list your issuer URL. - If a person you took access away from can still call tools, their token was issued before the policy changed, and it keeps working until it expires. To see the refusal yourself, choose Clear authentication in Claude Code and sign in again.