Chapter 1: Set up Keycard

This chapter is all Keycard console, no code. The MCP server keeps running exactly as it is. You’ll make one thorough trip through the Keycard console and register everything the rest of the workshop needs: how people sign in, the resources your server will need credentials for, and the application that represents the server itself.

Every chapter after this changes exactly one thing in the codebase. When Chapter 4 requires a Supabase credential or Chapter 6 swaps an API key for Linear OAuth, the console will be ready to go. You’ll see the authorization story come together, because you configured it here and you know what each piece is for.

You don’t need to memorize any Keycard concepts up front. We’ll define each piece as we create it.

Sign up for Keycard

1. Go to the Keycard AIE Workshop Signup page and enter your Keycard beta access code (provided by workshop instructors), then click Sign up with GitHub.

2. Log into GitHub, if you’re not logged in already. Click Authorize on the GitHub consent screen.

3. Go to console.keycard.ai and click “Continue with GitHub” to create your Keycard account.

4. Once logged in, you’ll land on your Keycard console homepage.

Take the tour

Your Keycard console isn’t empty. Before adding anything, explore what’s already there. The prepopulated entities demonstrate every concept you’re about to use.

• Applications has the Keycard CLI and Keycard ID Zone, both marked Keycard provided. Applications are runtimes that access Keycard; the CLI is a runtime that Keycard ships so its own command-line tool can act. The Keycard ID Zone application allows the Keycard Identity Provider to log in SSO users and manages the SSO Provider and credentials. Your MCP servers, agent SDKs, etc. are also applications because they access Keycard to exchange tokens.

• Resources already lists two: the Events API and OpenID Connect UserInfo. These are Keycard endpoints that return data on logging and Keycard users. Keycard registers them the same way you’ll register everything else. Even the platform’s own APIs play by the resource rules: if an agent wants a token, they have to be registered and governed.

• People are the users registered with your Keycard. You can change users’ roles and invite users. Each person’s identity provider is also listed.

• Policies contains one default policy set that allows applications to access resources on behalf of users. You’ll add a second policy set in Chapter 7. Policies are additive, with forbids overriding allows: if any policy forbids a request, it’s rejected, and if all policies allow it, it’s allowed. Since the Keycard platform is “deny by default,” the provided default policy set opens things up so you can get started quickly.

• Providers lists three items: Keycard ID (Keycard login with username/password), Zone Provider (OAuth providers), and the Zone Vault Provider (secrets vault). A provider issues authentication credentials to users and applications, and issues access credentials that permit users and agents to access resources.

• Under the Activity heading, you’ll find Sessions and Audit Log. The audit log is empty-ish now. It will not stay that way, and watching it fill up tells the story of progression in this workshop.

Grab your Keycard URLs

Keycard console

1. Under the Organization heading in the sidebar, click Settings. Note your OAuth URLs near the bottom of the page.

2. Keycard is an OAuth issuer. An issuer is an authorization server that issues tokens. Keep your Issuer URL handy. In Chapter 2 it becomes KEYCARD_URL, the issuer your MCP server trusts tokens from.

3. You’ll also find your Redirect URL under OAuth. This is the callback your identity provider sends users back to after they sign in. You’ll need it to set up external OAuth providers, like Linear.

Create the Keycard application

When we have a collection of resources, something needs to access them. Runtimes that access resources through Keycard are applications, and your MCP server is one. The application is your MCP server’s identity in Keycard. It’s what authenticates to Keycard when the MCP server exchanges tokens, what users grant access to, and what policies constrain.

Keycard console

1. Go to Applications → Add Application.

2. Configure the app:

   Application Name:

   Keycard Workshop MCP Client

   Identifier:

   urn:workshop:mcp:client

   Consent: Leave it on Required.

3. Create the application, then open its Application Credentials tab and click Add credential. You’ll be offered four ways an application can prove its identity.

   Choose Client ID & Secret.

4. The console shows you the generated client_id and client_secret once. Copy both into your .env now, at the bottom:

   .env

   KEYCARD_CLIENT_ID=<your-client-id>
   KEYCARD_CLIENT_SECRET=<your-client-secret>

   After you click “Done,” the console will only show that a credential exists. If you lose the secret, delete the credential and add a new one.

Consent: required vs. implicit

Required consent means the first time an agent connects on your behalf, you have to explicitly approve what it’s asking for, in your browser, before any token is minted.

Implicit consent skips that screen. We want the consent dialog because your (the user’s) approval builds the delegation story, and you’ll walk through it deliberately in Chapter 3.

Workload Identity vs. Client ID & Secret

The client secret is the only secret that stays on disk in this workshop.

In production, use Workload Identity Federation (WIF): this eliminates the long-lived client secret entirely. Your deployment platform attests to your server’s identity, Keycard verifies that cryptographically, and the app proves itself with short-lived, platform-signed tokens. Because that security comes from the deployment platform, WIF needs a real deployment, which is why we use client ID and secret for local dev. When you deploy, choose Workload Identity instead and configure it in your environment. We’ll return to WIF at the end of the workshop.

Locally, you can use the keycard CLI to eliminate secrets on disk. You authenticate with Keycard and the CLI brokers credentials into a process at launch. We don’t use the CLI in this workshop because it currently runs only on macOS with a CLI-launchable agent, and the workshop supports more operating systems and agent runtimes than that. If you have a Mac and Claude Code and would like to use the CLI to completely remove all secrets from .env, talk to an instructor!

Register the four resources

A resource is anything an agent gets a credential for: your own MCP server, a database, or a third-party service. Registering the resource tells Keycard “you will mint, store, broker, govern, and audit credentials for this entity.”

The server touches four resources, all of which you’ll register in the next several sections:

Resource	Identifier	Credential provider
Workshop MCP Server	http://localhost:8000/mcp	Zone Provider
Supabase Database	https://tsfavofmgkbyuujubppe.supabase.co	Zone Vault Provider
Anthropic API	https://api.anthropic.com	Zone Vault Provider
Linear API	https://api.linear.app	Linear (auto-provisioned from the catalog)

Two of these come from the instructor: the Supabase project URL with its secret API key, and an Anthropic API key. You’ll create your own OAuth app for Linear shortly.

Bring your own resources

You can also use your own free Supabase project (run data/seed.sql from the mcp-server/ reference folder in its SQL Editor, then create a secret key under Settings → API Keys and note the project URL) and your own Anthropic API key. You’ll create the Linear OAuth app yourself either way, but if you’re not in the shared workshop workspace, you can use your own Linear workspace.

Your MCP server

You’ve already added your MCP server as an application, which gave it an identity and the ability to call other resources. Now you’ll add it as a resource as well, because your coding agent needs to call the MCP server as a resource.

Why the MCP server is both an application and a resource

The MCP server sits in the middle of the call chain (User -> MCP client -> MCP server -> downstream resources), so it plays both roles:

Application (actor): the MCP server uses its own credentials (KEYCARD_CLIENT_ID, KEYCARD_CLIENT_SECRET) to authenticate to Keycard, then exchanges the user’s token for credentials to the downstream resources (Supabase, Anthropic, Linear) it calls on the user’s behalf.

Resource (target): the MCP client (in this case, your coding agent) needs access to your MCP server. The client’s token (your coding agent’s access, as it acts on your behalf) is intended for the MCP server resource. Access scopes and policy are evaluated based on authorization with a resource. Setting your MCP server up as a resource lets applications call it, enables scopes, and allows you to write policies that govern access to it.

In this workshop, your other components are downstream third party resources. They don’t call any additional resources, so they only play one role. The MCP server is both, which is also what builds the delegation chain correctly (client -> MCP server, MCP server -> downstream resource). If you built your own custom agent and wanted it to call your MCP server, that agent would be configured in Keycard as an application because it calls resources, but doesn’t receive access requests from other clients.

Keycard console

1. Go to Resources → Add Resource → Add Manually. (You’ll use the resource catalog for Linear later.)

2. Set the resource Name:

   Workshop MCP Server

   Identifier is your MCP endpoint, including the /mcp path:

   http://localhost:8000/mcp

   This exact string matters. When your server verifies a token in Chapter 2, it checks that the token’s audience matches this identifier, and Keycard compares it as an exact string. http://localhost:8000 without the path, or with a trailing slash, will not match. Type it exactly as above.

   Leave Use Gateway off.

3. Set Provided by Application by selecting Keycard Workshop MCP Client in the dropdown. Your application provides this resource: the MCP endpoint is the part of your server that clients get tokens to access, and the application is the server. This is the only resource today that gets a provided-by; the other three are external services your app merely uses.

4. Set the Credential Provider to the Zone Provider (Keycard STS), and click Protect Workshop MCP Server.

   Different types of Zone Credential Providers

   Keycard offers several credential providers. Your MCP server is your own endpoint, so Keycard itself issues and verifies its tokens. STS stands for Security Token Service: Keycard is a token-brokering authorization server.

   Use the Zone Provider for things you build, and use third-party providers only for the third parties’ own APIs.

   The Zone Vault Provider is for static secrets, and we’ll use it next.

Supabase, in the vault

The support tickets are moving from a static JSON file to a Supabase database in Chapter 4, and reading them will require a credential: the project’s secret API key (the sb_secret_…; Supabase’s older guides call its predecessor the service-role key). That key is exactly the kind of secret that usually ends up in .env. Instead it goes in your Keycard vault. In Chapter 4 your server will obtain it per request, with every retrieval audited. You’re registering the resource and storing the secret (encrypted, in the vault) now; the code catches up later.

Keycard console

1. Click Resources → Add Resource → Add Manually.

   Name:

   Supabase Database

   Set Identifier to the workshop’s Supabase project URL:

   https://tsfavofmgkbyuujubppe.supabase.co

2. Set the Credential Provider to the Zone Vault Provider and click Protect Supabase Database.

3. Open the resource’s Credentials tab and click Add credential.

   Name it:

   SUPABASE_SECRET_KEY

   In the Token field, paste the secret key (provided by workshop instructors).

   Click Create.

Third party resources are not provided by our application

Remember, the MCP server is the only resource “provided by” the application. Downstream third party resources aren’t served by the app. They could be used by any client, not just our server.

Anthropic, in the vault

You’ll add the instructor-provided Anthropic API key to the Keycard vault as well. In Chapter 5 the server uses an LLM to mask PII before it crosses into Linear. The Anthropic API key is another static secret that will never be stored on disk.

Keycard console

1. Click Resources → Add Resource → Add Manually.

   Name:

   Anthropic API

   Identifier:

   https://api.anthropic.com

2. Credential Provider: Zone Vault Provider. Protect it.

3. On the Credentials tab, add a credential with the Name:

   ANTHROPIC_API_KEY

   In the Token field, add the instructor-provided API key. Create the credential.

Anthropic API key will be deleted after the workshop

The Anthropic API key is a temporary, limited key created just for this workshop. It will be deleted afterward. If you want to keep playing with the code after the workshop, sign up for your own free Anthropic account and create a new API key to replace ours in the vault.

If you already have your own Anthropic API key, you can use it for the workshop now.

Linear, behind OAuth

You’ll set up Linear differently, using OAuth 2.0. The Linear API supports OAuth 2.0: it can mint scoped, short-lived, per-user tokens on demand. So instead of storing a static key, you configure a provider that can negotiate access, and Keycard handles the negotiation every time your server needs a token.

Linear is also in Keycard’s resource catalog, so the Keycard configuration is mostly automatic. However, you do need to create and configure a Linear OAuth app first.

Only Linear admins can create OAuth apps

Due to changes made by Linear as of December 2025, now only Linear workspace admins can create OAuth apps. After accepting your Linear invite, notify the workshop instructors and you’ll be granted admin privileges. If you accepted your invite prior to the workshop, you may already be an admin. You can check by clicking the link in Step 1 below.

Linear

1. Create your Linear OAuth app in the workshop workspace. Go to linear.app/keycard-workshop/settings/api/applications/new.

   Set the Application name to:

   <your name> OAuth App

   so you can tell yours apart from everyone else’s in the shared workspace.

   Fill in your Developer name.

   In the Redirect URIs field, paste your Keycard Redirect URL, the URL you noted in Keycard Settings earlier.

2. Click Create, then note your Linear Client ID and Client secret.

   Everyone’s app lives in one Linear workspace, but each has a different ID and authorizes access from a different Keycard account. Later, we’ll see just how important identity delegation is in a shared space.

Keycard console

1. Back in Keycard: Resources → Add Resource → Explore Resources, and pick Linear API from the catalog. Because the catalog already knows Linear’s endpoints, most of the configuration is done for you.

2. Fill in the Client ID and Client secret from the Linear OAuth app you just created. Click Protect Linear API.

3. On the Linear API resource page, at the bottom you’ll see Active scopes. read and write are pre-populated. Click Add scope and add:

   issues:create

   Then click Save Changes.

Connect application dependencies

Now that your resources are configured, tell Keycard your MCP application is allowed to ask for them. An application provides its own endpoints and depends on everything it accesses.

Keycard console

1. Open Applications → Keycard Workshop MCP Client → Dependencies → Add dependency.

2. Check: Anthropic API, Linear API, and Supabase Database, then click Connect.

The dependency list is your MCP server’s entire blast radius. It can request credentials for these resources. When you add policy in Chapter 7, you’ll learn how to further restrict access within these providers.

Nothing has changed on the MCP server yet

Your MCP server is still in its initial, insecure state. You’ve configured Keycard, describing what your server is, who its people are, and what it should be able to access. In Chapter 2, you will add the Keycard SDK to your MCP server.

Checkpoint

• You have a Keycard application gives your MCP server an identity (client ID and secret).
• Keycard has 4 new registered resources:
  • your MCP endpoint at http://localhost:8000/mcp on the Zone Provider,
  • Supabase, and
  • Anthropic API with keys stored in the vault, and
  • Linear API authorized by an OAuth provider with scopes read, issues:create, write.
• The Keycard Workshop App exists with consent required, provides the MCP resource, depends on your third party resources, and its client credentials are in your .env.