MCP Authentication¶

In this lab we explore how to configure MCP authentication and authorization in agentgateway, decoupling that concern from the business logic in the backend MCP server.

You will explore exposing a different set of tools to the user based on whether they're authenticated, and if authenticated, based on their role, obtained from the user's JWT token.

Setup¶

For this lab, instead of configuring a full-fledge identity provider such as KeyCloak for the authentication, we provide pre-minted JWT tokens in the form of environment variables READER_JWT and PUBLISHER_JWT.

Follow these instructions to configure a simple stub server to serve the JWKS keyset in the background:

python3 scripts/fake_idp.py >/tmp/fake_idp.log 2>&1 &

The same process also writes the file fake_idp.env to load the JWT tokens as environment variables.

A proxy configured with MCP Authentication & Authorization¶

Review the following agentgateway configuration:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49

# yaml-language-server: $schema=https://agentgateway.dev/schema/config
config:
  database:
    url: sqlite://./data.db
llm:
  models:
  - name: trend-pro
    provider: openAI
    params:
      baseUrl: http://localhost:11434/v1
      model: qwen3:8b
      apiKey: ollama-does-not-check-this
mcp:
  policies:
    mcpAuthentication:
      mode: optional
      issuer: http://localhost:9000
      audiences:
      - http://localhost:3000/mcp
      jwks:
        url: http://localhost:9000/.well-known/jwks.json
      resourceMetadata:
        resource: http://localhost:3000/mcp
        scopesSupported:
        - read:all
        bearerMethodsSupported:
        - header
    mcpAuthorization:
      rules:
      - mcp.tool.target == "trends"
      - mcp.tool.target == "publish" && mcp.tool.name == "get_public_feed"
      - mcp.tool.target == "workspace" && has(jwt.sub)
      - mcp.tool.target == "publish" && has(jwt.roles) && "publisher" in jwt.roles
  targets:
  - name: trends
    stdio:
      cmd: .venv/bin/python3
      args:
      - ./mcp-servers/trends_server.py
  - name: workspace
    stdio:
      cmd: .venv/bin/python3
      args:
      - ./mcp-servers/workspace_server.py
  - name: publish
    stdio:
      cmd: .venv/bin/python3
      args:
      - ./mcp-servers/publish_server.py

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48

# yaml-language-server: $schema=https://agentgateway.dev/schema/config
config:
  database:
    url: sqlite://./data.db
llm:
  models:
  - name: trend-pro
    provider: gemini
    params:
      model: gemini-3.5-flash-lite
      apiKey: "$GEMINI_API_KEY"
mcp:
  policies:
    mcpAuthentication:
      mode: optional
      issuer: http://localhost:9000
      audiences:
      - http://localhost:3000/mcp
      jwks:
        url: http://localhost:9000/.well-known/jwks.json
      resourceMetadata:
        resource: http://localhost:3000/mcp
        scopesSupported:
        - read:all
        bearerMethodsSupported:
        - header
    mcpAuthorization:
      rules:
      - mcp.tool.target == "trends"
      - mcp.tool.target == "publish" && mcp.tool.name == "get_public_feed"
      - mcp.tool.target == "workspace" && has(jwt.sub)
      - mcp.tool.target == "publish" && has(jwt.roles) && "publisher" in jwt.roles
  targets:
  - name: trends
    stdio:
      cmd: .venv/bin/python3
      args:
      - ./mcp-servers/trends_server.py
  - name: workspace
    stdio:
      cmd: .venv/bin/python3
      args:
      - ./mcp-servers/workspace_server.py
  - name: publish
    stdio:
      cmd: .venv/bin/python3
      args:
      - ./mcp-servers/publish_server.py

The configuration has both authentication and authorization sections. The authentication mode is set to optional. Whether a user is authenticated has a bearing on the interpretation of the authorization rules, some of which reference claims in the user's JWT token. When the user is unauthenticated, those rules return "false" and certain tools are not available.

From one terminal, launch agentgateway:

agentgateway -f configs/mcp-identity.yaml

agentgateway -f configs/mcp-identity-gemini.yaml

Scenario 1: Unauthenticated user¶

In a second terminal, begin by loading the environment variables for the two JWT tokens:

source fake_idp.env

Start the agent with a request that demands access to certain tools that are not available to unauthenticated users:

python3 agent/trendwatch.py \
  "Build today's digest from the trending discussions, then call workspace_save_digest to write it to disk. Do not finish until you have saved it, and report the file path the tool returns."

The trending discussions will be obtained, but the agent will not be able to go any further: it cannot call "save_digest".

Scenario 2: User with read-only access¶

The MCP_TOKEN environment variable is used as the identity of the user making the request:

export MCP_TOKEN=$READER_JWT

Now we have a user that has access to more tools, the workspace tools are accessible, and so the agent should be able to fulfill the request:

python3 agent/trendwatch.py \
  "Build today's digest from the trending discussions, then call workspace_save_digest to write it to disk. Do not finish until you have saved it, and report the file path the tool returns."

You should be able to confirm that a "digest" file was written to the folder out/:

ls out/

If we ask the agent to "post the digest" which is a "publish" type of action however, the agent is unable to fulfill that request:

python3 agent/trendwatch.py "post that digest to social"

Scenario 3: User with read-write access¶

Finally, set the identity of the caller to someone with "publisher" role or capability:

export MCP_TOKEN=$PUBLISHER_JWT

Now the agent will have access to all the tools, and should be able to perform a publish:

python3 agent/trendwatch.py \
  "Build today's digest from the trending discussions, get the single top trending AI related item from the trending discussions, then publish it by calling publish_post_to_social. Report only the exact JSON the tool returns, then call publish_get_public_feed and show me the feed to confirm the post landed."

Summary¶

In this lab, authentication and authorization for a backend MCP server was configured at the proxy. The benefit of employing a proxy is the ability to decouple the implementation of cross-cutting concerns such as security from the logic of the backend workload, be it an MCP server or some other type of backend. No changes to the backend service were required to implement the security layer.