Skip to content

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.

  1. MCP client Signs the person in through Keycard and gets a token for the gateway’s MCP endpoint.
  2. Keycard Issues the token only if policy lets that person reach the MCP server.
  3. agentgateway Checks the token against Keycard’s signing keys and refuses any request without a valid one.
  4. MCP server Receives only the requests the gateway lets through.
  • 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 npx can run the sample MCP server.
  • curl and jq.

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:

Terminal window
mkdir keycard-agentgateway && cd keycard-agentgateway
  1. 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.

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

  1. Write the gateway config

    Create config.yaml in your working directory:

    # yaml-language-server: $schema=https://agentgateway.dev/schema/config
    gateways:
    default:
    port: 3000
    routes:
    - backends:
    - mcp:
    targets:
    - name: everything
    stdio:
    cmd: npx
    args: ["-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/mcp
    policies:
    # 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: strict
    issuer: <keycard-issuer-url>
    audiences:
    - http://localhost:3000/mcp
    jwks:
    url: <keycard-issuer-url>/openidconnect/jwks
    resourceMetadata:
    resource: http://localhost:3000/mcp
    scopesSupported:
    - mcp:tools
    bearerMethodsSupported:
    - header

    Replace <keycard-issuer-url> in both places with your issuer URL. audiences and resource must match the Resource identifier exactly, including the /mcp path, because Keycard puts that identifier in the aud claim of every token it issues for the MCP server.

  2. Run the gateway

    Terminal window
    agentgateway -f config.yaml

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

  1. Add the gateway’s MCP endpoint

    Terminal window
    claude mcp add --transport http everything http://localhost:3000/mcp

    For Cursor, add the same URL under mcpServers in .cursor/mcp.json.

  2. Sign in

    Run /mcp inside 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.

  3. Call a tool

    Ask Claude to run the echo tool. 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:issue event for the connection.

agentgateway runs in the foreground, so run these in a second terminal. Step 3 needs the Admin Role.

  1. 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-Authenticate header points the client at the metadata:

    HTTP/1.1 401 Unauthorized
    www-authenticate: Bearer resource_metadata="http://localhost:3000/.well-known/oauth-protected-resource/mcp"
    {"error":"unauthorized","error_description":"JWT token required"}
  2. Call the gateway with a token

    Create a keycard.toml in 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/mcp
    MCP_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 OK
    content-type: text/event-stream
    mcp-session-id: f4d2e962-ae16-4aa4-9199-7db1ed05fba9
    event: message
    data: {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-06-18", ... ,"serverInfo":{"name":"mcp-servers/everything", ... }}}
  3. Take one person’s access away

    The default policies permit everyone. A forbid overrides a permit, 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 forbid inside 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 gateway
    forbid (
    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.com with 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 for http://localhost:3000/mcp, so Claude Code can’t connect.

  1. Stop agentgateway with Ctrl+C.
  2. Remove the MCP server from Claude Code:
  3. In Keycard Console, activate default-zone-policies again, then remove the Agentgateway Access Policy Set.
  4. Delete the Everything MCP Server Resource, and the Claude Code client under Applications.
  • 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 mcpAuthorization policy with rules on Keycard claims such as jwt.sub or jwt.keycard_app_id, combined with mcp.tool.name.
  • The recipe runs on localhost. To move off it, register the gateway’s public URL as the Resource identifier and set audiences and resourceMetadata.resource to match.
  • If a request with a token still gets 401, check that audiences in config.yaml matches the Resource identifier exactly, including the /mcp path.
  • 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_servers should 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.

Did this recipe work for you?