Chapter 2: Protect the MCP server

Right now anyone who can reach localhost:8000 can call every tool, because the server has no way to identify the caller. You’re going to put a Keycard bearer-token check in front of /mcp. After this, a request without a valid token gets a 401: Unauthorized error, and the only way to get a valid token is to authenticate with Keycard.

Verifying a JSON Web Token (JWT) properly means fetching the issuer’s signing keys, checking the signature, the issuer, the audience, the expiry, and getting everything right. The @keycardai/mcp SDK does all of this, so this chapter teaches you to implement it correctly and understand what it’s doing.

Keycard SDK middleware

You’ll implement two pieces of middleware from the Keycard MCP SDK:

• mcpAuthMetadataRouter advertises how to authenticate. It serves a small metadata document at a well-known URL that tells any agent “here’s the issuer to get a token from.” It simply provides information; it does not enforce.
• requireBearerAuth is the enforcement layer. This middleware runs before your tool handler and rejects the request unless it carries a valid token from Keycard, minted for this resource.

The metadata is what makes enforcement usable: when the server rejects an anonymous request, its 401 points back at the metadata, so an agent can discover where to log in and try again.

Install the SDK

From inside support-escalation/ (the same directory you’ve been working in since Chapter 0):

Command line

npm install @keycardai/mcp@0.10.0

Add Keycard information to .env

Open .env and add two values from Chapter 1:

.env

# The Keycard URL that issues and verifies tokens from Keycard > Settings.
KEYCARD_URL=<your issuer URL>

# This server's resource URI, exactly as you registered it in Keycard.
MCP_RESOURCE_URL=http://localhost:8000/mcp

KEYCARD_URL is the issuer your MCP server trusts (no trailing slash). MCP_RESOURCE_URL is the audience your MCP server requires. The next section shows why each is important.

Implement the middleware

Open src/server.ts. We need to read those two new env vars, mount the metadata router, and add requireBearerAuth middleware to the /mcp route.

Prompt your coding agent

In src/server.ts, add Keycard bearer-token auth. Import mcpAuthMetadataRouter from “@keycardai/mcp/server/auth/router” and requireBearerAuth from “@keycardai/mcp/server/auth/middleware/bearerAuth”. Read KEYCARD_URL and MCP_RESOURCE_URL from the environment, failing clearly if either is missing. Mount mcpAuthMetadataRouter with the issuer set to KEYCARD_URL and scopesSupported of read and issues:create. Add requireBearerAuth as middleware on the POST /mcp route, with issuers set to KEYCARD_URL and audiences set to MCP_RESOURCE_URL, before the existing handler. Don’t change the handler itself.

This is what your coding agent should build. First, it will add the imports and a small helper to read required env vars (you’ll notice linear.ts has the same little helper; each file keeps its own copy so it reads standalone, and so this chapter’s change stays entirely inside server.ts):

import { requireBearerAuth } from "@keycardai/mcp/server/auth/middleware/bearerAuth";
import { mcpAuthMetadataRouter } from "@keycardai/mcp/server/auth/router";

/** Read a required env var, failing with a useful message instead of a cryptic error later. */
function requireEnv(name: string): string {
  const value = process.env[name];
  if (!value) {
    throw new Error(`Missing ${name} — copy .env.example to .env and fill in the workshop values.`);
  }
  return value;
}

const KEYCARD_URL = requireEnv("KEYCARD_URL");
const MCP_RESOURCE_URL = requireEnv("MCP_RESOURCE_URL");

Then it should mount the metadata router so the server advertises how to authenticate:

app.use(
  mcpAuthMetadataRouter({
    oauthMetadata: { issuer: KEYCARD_URL },
    scopesSupported: ["read", "issues:create"],
    resourceName: "Support Escalation MCP",
  }),
);

The read and issues:create scopes are the ones you gave to the Linear API resource in Keycard in Chapter 1. You advertise them in metadata because when an agent logs in, Keycard passes the requested scopes through your app’s dependency chain to each resource. You advertise what your tools will actually need downstream, including the Linear scopes you configured. An agent then reads this metadata and is supposed to only ask for the specified scopes.

The missing write scope

Notice write isn’t on the list, even though the Linear resource and the delete_issue tool support and use it. The MCP server is capable of deleting issues, but you don’t advertise that scope because this agent shouldn’t delete. But scopesSupported metadata is a hint, not a guardrail. Nothing here actually prevents an agent from calling delete_issue. The agent could decide to request a write scope on its own, whether write is in the metadata or not.

This metadata tells agents what scopes to ask for, but enforcing scopes here would reject any token that lacks them, and you can’t assume every client requests these scopes. This chapter secures the open /mcp endpoint, which you accomplish via issuer and audience checks. You’ll come back to these scopes again in Chapter 7 when you write a policy.

Next, the agent should add bearer auth middleware in front of /mcp:

app.post(
  "/mcp",
  requireBearerAuth({ issuers: KEYCARD_URL, audiences: MCP_RESOURCE_URL }),
  async (req, res) => {
    // ...the existing handler is unchanged...
  },
);

When done, the agent will prompt you to run the following install in in support-escalation/ again to download the new Keycard SDK dependency:

Command line

npm install @keycardai/mcp@0.10.0

Do so before testing the server.

Issuers and audiences

Inspect the requireBearerAuth() middleware in support-escalation/src/server.ts. This verifies two important things:

• issuers rejects any token not signed by Keycard. Without it, the middleware would accept any signed JWT from anywhere. (The SDK throws if you don’t provide a verifier or issuers, precisely so you can’t ship that mistake.)
• audiences binds the token to this resource. Keycard mints tokens for more than one audience: you saw the prepopulated Events API and OpenID Connect UserInfo resources in Chapter 1, and a busier configuration might hold several MCP servers. A token minted for a different resource is signed, valid, and passes the issuer check, even if it should not call your tools. The audience check confirms the token’s aud claim matches http://localhost:8000/mcp so a token meant for one resource can’t be replayed against another.

The key takeaway is to only trust your Keycard, and only accept tokens actually meant for your MCP server.

MCP server rejects anonymous calls

Restart the server if it isn’t already running (npm run dev), then use curl to make the same kind of anonymous call your agent made in Chapter 0:

Command line

curl -i -X POST http://localhost:8000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

You get a 401, and among the response headers (alongside the usual Date, Content-Type, and friends) is the one that shows the fruits of our labor:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="http://localhost:8000/.well-known/oauth-protected-resource/mcp"

The WWW-Authenticate header is the metadata doing its job. It’s not just a rejection; it tells the caller exactly where to look to find out how to authenticate. Open that metadata URL in your browser and you’ll see your issuer listed. That’s the breadcrumb an agent follows to start an OIDC login, which is what we’ll do in Chapter 3.

Locked out on purpose

If you still have your agent connected from Chapter 0, try a tool call now:

Prompt your coding agent

Use support-escalation to list open tickets.

It will either fail, or the agent will helpfully inform you that you need an OAuth token to access the MCP server. The agent has no token, and the server now requires one. The endpoint that accepted anyone now accepts no one, until they can prove who they are.

A valid token would get a 200 (you’ll see that for yourself next chapter, when your agent logs in and reconnects).

Helpful agents might present a URL

A particularly helpful agent might parse the WWW-Authenticate header, recognize it’s an OAuth flow, and offer you a clickable URL to dynamically register your agent and start the login flow. If yours does, feel free to click it (if it doesn’t, don’t worry, we’ll walk through it next chapter). If successful, it’ll take you to the GitHub login and/or consent screen, followed by the Keycard consent screen. You’re getting a sneak preview for what’s coming next.

Checkpoint

• An anonymous curl to /mcp returns 401 with a WWW-Authenticate header pointing at your resource metadata.
• Your Chapter 0 agent can no longer call the tools.