Original elicitations

Learn how agentgateway intercepts requests and triggers on-demand token elicitation when a stored upstream token is missing.

About this guide

In this guide you explore how to access the GitHub MCP server from the MCP inspector MCP client. The GitHub MCP server requires a valid GitHub personal access token (PAT) to be present in the Authorization request header to grant access to its tools, such as get_latest_release. The PAT can be retrieved by completing the GitHub OAuth consent flow.

Instead of injecting the PAT into the HTTPRoute directly as shown in the Connect via HTTPS MCP example, you explore how to leverage elicitations to complete the GitHub authorization flow. After you authorize the elicitation, the GitHub access token is stored in the STS server. The agentgateway proxy looks up the token and automatically injects the token into the Authorization header in subsequent requests.

    sequenceDiagram
    participant Client as MCP Client
    participant GW as agentgateway
    participant STS as STS
    participant UI as agentgateway UI
    participant GitHub as GitHub OAuth
    participant Server as GitHub MCP Server

    Client->>GW: Request with JWT
    GW->>STS: Token lookup <br/>(no GitHub token found)
    STS-->>GW: Token not found
    GW-->>Client: 500 + elicitation URL

    Note over Client,UI: User opens elicitation URL in browser

    Client->>UI: Open elicitation URL (Keycloak login)
    UI->>GitHub: Redirect to GitHub <br/>OAuth consent
    GitHub-->>UI: Authorization code
    UI->>STS: Exchange code for <br/>GitHub access token
    STS-->>UI: Token stored

    Note over Client,GW: User retries the request

    Client->>GW: Retry request with JWT
    GW->>STS: Token lookup <br/>(GitHub token found)
    STS-->>GW: GitHub access token
    GW->>Server: Request with GitHub token
    Server-->>GW: Response
    GW-->>Client: Response

Before you begin

Set up the elicitation infrastructure.

The steps in this example assume that you want to use the OAuth GitHub app that you set up when you deployed the elicitation infrastructure. To use a different app, create the app and add its client ID and secret to a Kubernetes secret. You can follow the steps in the Set up an OAuth app.

Set up MCP elicitations

Create an MCP backend for the GitHub MCP server.

kubectl apply -f- <<EOF
apiVersion: agentgateway.dev/v1alpha1
kind: AgentgatewayBackend
metadata:
  name: github-mcp-backend
  namespace: agentgateway-system
spec:
  mcp:
    targets:
    - name: mcp-target
      static:
        host: api.githubcopilot.com
        port: 443
        path: /mcp/
        policies:
          tls:
            sni: api.githubcopilot.com
EOF

Create an HTTPRoute that routes traffic to the GitHub MCP server along the /mcp-github path. To properly connect to the MCP server, you must allow traffic from http://localhost:8080, which is the domain and port you expose your agentgateway proxy on later. If you expose the proxy under a different domain, make sure to add this domain to the allowed origins.

kubectl apply -f- <<EOF
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: mcp-github
  namespace: agentgateway-system
spec:
  parentRefs:
  - name: agentgateway-proxy
    namespace: agentgateway-system
  rules:
    - matches:
      - path:
          type: PathPrefix
          value: /mcp-github
      filters:
        - type: CORS
          cors:
            allowHeaders:
              - "*"
            allowMethods:
              - "*"
            allowOrigins:
              - "http://localhost:8080"
      backendRefs:
        - name: github-mcp-backend
          group: agentgateway.dev
          kind: AgentgatewayBackend
EOF

Create an EnterpriseAgentgatewayPolicy resource that enables an elicitation flow for your MCP backend. In this example, you use the default elicitation mode that exchanges your JWT token for a GitHub token. This way, the agentgateway proxy injects the GitHub token from the STS server directly into the Authorization request header when connecting to the GitHub MCP server.

kubectl apply -f- <<EOF
apiVersion: enterpriseagentgateway.solo.io/v1alpha1
kind: EnterpriseAgentgatewayPolicy
metadata:
  name: github-mcp-elicit-policy
  namespace: agentgateway-system
spec:
  targetRefs:
  - name: github-mcp-backend
    kind: AgentgatewayBackend
    group: agentgateway.dev
  backend:
    tokenExchange:
      elicitation:
        secretName: elicitation-oidc
EOF

Test the elicitation

Generate a JWT token for the user1 user that you set up. You use this JWT token to trigger the elicitation flow.

export USER_TOKEN=$(curl -d 'client_id=fe-client-1' \
 -d 'username=user1' \
 -d 'password=Password1!' \
 -d 'grant_type=password' "$KEYCLOAK_URL/realms/agentgateway/protocol/openid-connect/token" | jq -r .access_token)
echo $USER_TOKEN

Send a request to the GitHub MCP server. Include the JWT that you retrieved earlier in the Authorization header. Verify that the request returns a 500 HTTP response code, because the agentgateway proxy could not find a GitHub access token in the STS server. The proxy returns the URL to the elicitation view in the UI.

You can alternatively use the MCP inspector tool to connect to your MCP server and walk through the elicitation flow.

curl -vik -X POST http://localhost:8080/mcp-github \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-protocol-version: 2025-06-18" \
  -H "Authorization: Bearer $USER_TOKEN" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18",
      "capabilities": {},
      "clientInfo": {"name": "curl-client", "version": "1.0"}
    }
  }'

Example output:

< HTTP/1.1 500 Internal Server Error
HTTP/1.1 500 Internal Server Error
< content-type: application/json
content-type: application/json
< content-length: 302
content-length: 302

< 

* Connection #0 to host localhost left intact
{"jsonrpc":"2.0","id":1,"error":{"code":-32603,"message":"failed to send message: send error: http upstream error: http request failed: request needs a token exchange, but token not available in STS, info: TokenExchangeInfo { url: Some(\"http://localhost:8090/age/elicitations\"), status_url: None }"}}%

Open the elicitation URL that is returned in the previous command.
```
open http://localhost:8090/age/elicitations
```
Authorize the elicitation.
1. In the UI, find your elicitation and click Authorize. The UI redirects you to the GitHub OAuth consent form.
2. Log into your GitHub account and complete the OAuth consent. You are redirected back to the elicitation view in the UI.

Send another request to the GitHub MCP server. Verify that this time, the request succeeds. The agentgateway proxy automatically looks up the GitHub token from the STS server and injects it into the Authorization request header.

curl -s -X POST http://localhost:8081/mcp-github \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-protocol-version: 2025-06-18" \
  -H "Authorization: Bearer $USER_TOKEN" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18",
      "capabilities": {},
      "clientInfo": {"name": "curl-client", "version": "1.0"}
    }
  }'

Example output:

data: {"jsonrpc":"2.0","id":1,"result":
{"protocolVersion":"2025-06-18","capabilities":{"completions":{},
"prompts":{},"resources":{},"tools":{}},"serverInfo":
{"name":"github-mcp-server","title":"GitHub MCP Server",
"version":"github-mcp-server/
remote-7a549a1d5bbb399e4bc76c1f12a60afb9f211227","icons":
[{"src":"data:image/png;base64,...","mimeType":"image/png",
"theme":"light"},{"src":"data:image/png;base64,..","mimeType":"image/
png","theme":"dark"}]}}}

Cleanup

You can optionally remove the resources that you set up as part of this guide.

kubectl delete AgentgatewayBackend github-mcp-backend -n agentgateway-system 
kubectl delete httproute mcp-github -n agentgateway-system 
kubectl delete EnterpriseAgentgatewayPolicy  github-mcp-elicit-policy -n agentgateway-system

Set up the elicitation infrastructure MCP consent screen