Run Claude Code with the Keycard CLI

By the end of this guide, you’ll have:

• Claude Code running in a Keycard secure session, connected to an MCP server from the Catalog
• A session log of the tool calls your agent makes

You should be able to complete this guide in about 10 minutes.

1. Sign up for Keycard

   Go to console.keycard.ai, create your account, and sign in.

2. Install the Keycard CLI

   Install the Keycard CLI from your computer’s terminal:

   brew install keycardai/tap/keycard

3. Install the Keycard Claude plugin

   In the root of your project, run:

   keycard plugin install claude

   Claude Code turns the plugin on for that directory only. The plugin adds a set of Skills Claude uses to manage your Keycard setup.

4. Install an MCP server from the catalog

   The Keycard Catalog lets you install official MCP servers like Linear, Sentry, Notion, Jira, GitHub, and more. Pick one to install:

   1. Open Console → Resources → Add Resource → Explore Resources.

   2. Pick a server (this guide uses Linear MCP as the running example) and click Continue with Linear MCP. Console opens the new Linear MCP Proxy Resource when it’s ready: a Keycard MCP endpoint that fronts Linear’s MCP server, so your agent never holds a Linear token.

   3. On that Resource, click Add to Coding Agent → Claude Code, and copy the displayed claude mcp add command into your terminal:

      claude mcp add --transport http --scope user <server-name> <gateway-url>

5. Run your agent in a secure session

   Find the CLI configuration snippet with your Organization ID and Zone ID in the Keycard Console:

   1. Open Settings → Connection, then copy the CLI configuration code block.

   2. In the root of your project, create a keycard.toml and paste your CLI configuration into the file:

      [org]
      id = "<org-id>"
      
      [zone]
      id = "<zone-id>"

   Then start a Keycard-protected Claude Code session:

   keycard run claude

6. Use the MCP server

   Ask Claude to do something that calls the MCP server you installed. For example, if you’re using Linear:

   List my open Linear issues.

   On the first call, Keycard prompts you to authorize access between Keycard and Linear:

   

   Claude Code reports that Linear-MCP-Proxy needs authentication. Run /mcp, select Linear-MCP-Proxy and choose Authenticate, then click Allow access in the browser. The first time you connect Linear, Linear also asks you to Approve Keycard and pick your workspace. Then ask again.

7. Check the session log

   In your Keycard Console, click Sessions to see the tool calls made during your session with Claude.

Now that you have Claude Code running in a secure session with token exchange, here’s where to go next:

• Install more MCP and API servers for Sentry, Notion, Atlassian, Gmail, Slack, and more in the Catalog
• Access APIs on Behalf of Users so each agent call is scoped to the signed-in user’s identity, permissions, and audit attribution
• Run on Fly.io without secrets so workloads authorize every call with their own identity instead of long-lived API keys
• Grant an agent access to Snowflake so autonomous agents get their own scoped identity and audit trail, independent of any human

keycard run fails to start

• Verify keycard auth signin succeeded by running keycard auth whoami in the project directory
• Check that keycard.toml exists in the project root and that its [org] id and [zone] id match the ones shown in Console under Settings → Connection

MCP server OAuth fails on first tool call

• Open the application in Console → Applications and re-run the OAuth flow from the install dropdown
• Confirm your claude mcp add command used the correct Gateway URL