Chapter 3: Authenticate your agent

At the end of Chapter 2 you locked yourself out on purpose. Your agent still has the server in its config, but every call now comes back 401: Unauthorized because the MCP server demands an access token and your agent doesn’t have one. This chapter grants you access the right way: your agent signs in through Keycard, and from now on every call has a real identity that Keycard can see.

The fun part is, you don’t write any code in this chapter, and you don’t touch the console either. The server is already protected and already advertising how to authenticate. Your agent can follow that trail on its own. Your just have to let it, by triggering authentication and approving it in the browser.

Did your agent already help you log in?

Remember the note from the end of the last chapter about helpful agents offering an authorization URL? If you already went through the OAuth flow, good news: you’re already authenticated (but please do read how it works, and how to log in again if you get logged out).

How the agent knows how to log in

Remember the 401 from Chapter 2. That response included a WWW-Authenticate header pointing at your resource metadata, which points at Keycard. A well-behaved agent treats that as a set of instructions:

1. Your agent calls your MCP server endpoint, gets the 401, and reads the WWW-Authenticate header.
2. It follows the header to your protected-resource metadata, which names Keycard as the authorization server.
3. It reads Keycard’s OAuth metadata, which advertises a registration endpoint. The agent registers itself as a client on the spot. This doesn’t require a client ID or client secret because it’s Dynamic Client Registration. This is why you didn’t have to configure anything for your agent in Keycard in Chapter 1.
4. You’re already logged into Keycard, so your agent opens your browser and prompts you to approve access (this is the consent you set to required in Chapter 1).
5. Keycard returns a token scoped to your MCP server, the agent caches it, and voilà, you (and your agent) are in.

The agent is reacting to metadata the server already supplies. That’s why agent authentication doesn’t require any more code.

This is a localhost server, so there's no install step

If you’ve seen Keycard’s “Add to Coding Agent” button in your Workshop MCP Server resource settings, that’s for servers published in a catalog or behind a gateway. Yours runs on localhost, so there’s nothing to publish. You connect by pointing your agent at http://localhost:8000/mcp and letting OAuth discovery do the rest.

Connect your agent

Make sure your server is still running (npm run dev in support-escalation/). Then trigger authentication for your agent. Pick your tab below; the steps differ because each agent exposes the OAuth flow a little differently.

Sign into the keycard-workshop Linear workspace

Linear’s consent screen authorizes whichever workspace your browser is currently signed into. If you belong to more than one, switch to the keycard-workshop workspace in Linear before approving. Approving the wrong Linear workspace binds your authorization incorrectly, and escalation tool calls will later fail with a “team not found” error because your LINEAR_TEAM_ID lives in a different workspace.

Claude Code

Your server is already registered from Chapter 0, so you don’t re-add it. You just authenticate it now that it’s protected.

1. In Claude Code, run:

   /mcp

2. You’ll see support-escalation listed under Local MCPs and marked needs authentication. Select it and choose Authenticate.

3. Your browser opens and depending on if you already signed in last chapter, prompts you for GitHub authentication/consent, Keycard consent, and Linear consent. Log in and approve any access requests. When the flow completes, Claude Code announces the support-escalation server is connected.

If the browser redirect doesn't open

Claude Code listens on a random local port for the OAuth callback. If your browser can’t reach that port, re-run with a fixed port (claude --callback-port 8181) so the redirect target is stable, then try /mcp again.

Claude Desktop

Claude Desktop reaches your HTTP endpoint through mcp-remote (the bridge you set up in Chapter 0). mcp-remote runs the OAuth flow.

1. Fully quit and reopen Claude Desktop. On startup, mcp-remote tries to connect to the support-escalation MCP server, sees the 401, runs discovery, and opens your browser for authentication and authorization.

2. Sign in with GitHub / Keycard / Linear as necessary and approve access. mcp-remote catches the callback, exchanges it for a token, and caches it under ~/.mcp-auth.

3. The support-escalation tools are available again in the app.

stdio can't prompt you, but http can

In Chapter 0, you configured the MCP server with mcp-remote instead of a plain stdio command. A stdio server has no way to say “I need you to log in.” The HTTP transport mcp-remote does, so when consent expires or the server requires a token, it can open a browser and recover. A stdio setup would simply fail to start.

Codex

Codex connects to your endpoint over HTTP using the entry you added in Chapter 0, and authenticates on demand.

1. Trigger the login:

   Command line

   codex mcp login support-escalation

2. Your browser opens and depending on if you already signed in last chapter, prompts you for GitHub authentication/consent, Keycard consent, and Linear consent. Log in and approve any access requests. When the flow completes, Codex announces you’re logged in to the support-escalation server.

3. The support-escalation tools are available again.

Codex asks for the scopes you advertised

Remember the scopes_supported: ["read", "issues:create"] you mounted in Chapter 2? Codex reads it from your metadata and requests those scopes during login. A well-behaved agentic client asks for what the server says it offers. You’ll see read and issues:create show up on the token in the Keycard audit log in a moment.

Cursor

Cursor reaches your HTTP endpoint using the entry you added in Chapter 0, and runs the OAuth flow when the server requires it. You may need to log out and back in again to trigger the connection flow.

1. Open Settings (Cmd+Shift+J / Ctrl+Shift+J) → Features → Model Context Protocol. When Cursor hits the now-protected server and gets a 401, it runs discovery and surfaces support-escalation as needing authentication. Start the login from that panel (Cursor may also open your browser automatically when it detects the 401).

2. Your browser opens and, depending on whether you already signed in last chapter, prompts you for GitHub authentication/consent, Keycard consent, and Linear consent. Log in and approve any access requests.

3. Cursor catches the callback, exchanges it for a token, and the support-escalation tools are available again.

Make an authenticated call

With the agent reconnected, prompt it the same way you did in Chapter 0:

Prompt your coding agent

Using the support-escalation tools, list the open support tickets.

This time the call goes through with a token attached, and you get the tickets back. The request is no longer anonymous. Behind the tool response is a token Keycard minted for you, scoped to your MCP server resource.

Authentication and grants

The browser sign-in only interrupts you once. Keycard records your approval as a grant, and the agent caches the token, so later sessions reconnect silently until the grant or token expires. If you’ve signed into this resource before, you may not see a consent screen at all; Keycard honors the grant you already gave.

However, for security, grants can be short-lived. Whenever the grant expires, your agent will prompt you to re-authenticate when calling tools. This means if you walk away from your computer, the agent can’t keep calling tools on your behalf indefinitely. The session token also expires, but the agent can refresh it silently as long as the grant is valid.

See authentication in the audit log

Keycard console

1. Go to console.keycard.ai and click Audit Log in the sidebar.

2. Find the most recent credentials:issue event. Its Entity is your Workshop MCP Server resource, and its Actor is the client your agent registered for itself (you’ll see a name like MCP CLI Proxy for the mcp-remote bridge used by Claude Desktop, or your agent’s own registered client, e.g., Claude Code orCodex).

3. Click into the event. Under Actor Details you’ll see the type is an identity chain with two identities: the agent’s client and you, your GitHub email, listed as the User. The raw Request Information shows grant_type: authorization_code and scopes: ["read", "issues:create"].

Before this, there was no way to distinguish one caller from another. Your MCP server no longer sees an anonymous caller, and it no longer sees a faceless shared key. It recognizes your agent acting on your behalf, and explicitly logs that. Compare that to Chapter 0 where tool calls weren’t logged at all, and even if they were, they would have been indistinguishable from each other.

What you won't see yet, and why

Notice that the audit log shows the sign-in event and token, but not the individual get_support_tickets tool call. That’s expected at this point.

Right now your MCP server verifies the token locally (it checks the signature against Keycard’s keys without calling Keycard), so the tool calls themselves never reach the audit log.

In the next chapter, your MCP server begins exchanging that authentication token for downstream credentials on every call, and those exchanges will also show up in the audit log, always with you in the identity chain.

Checkpoint

• Your agent is connected through Keycard.
• get_support_tickets returns the tickets again (now with a token, not anonymously).
• Your Keycard audit log shows a credentials:issue event for your MCP resource with a two-identity chain naming you as the user.
• The MCP server that rejected everyone in Chapter 2 now accepts you, specifically, and can prove your identity.