Quickstart

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

• Keycard protecting all tool calls via policies
• Audit log of all tool authorization decisions

You should be able to complete this quickstart 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

   This gives you the keycard binary, Claude Code plugin, and a set of Skills Claude uses to configure your access policy.

3. Install the Keycard Claude plugin

   claude plugin marketplace add keycardai/plugins
   claude plugin install keycard-cli@keycardai

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 → Applications → Add Application → Explore MCP Servers.

   2. Pick a server (this quickstart uses Linear as the running example) and click Install. The server appears in your Applications list with a Keycard MCP Gateway URL.

   3. Open the installed application, 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. Click Zone → Zone Settings, 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

   Every tool call Claude makes is evaluated by Keycard before it runs.

6. Have the agent write a policy

   Keycard lets you control sensitive actions agents may take. Configure access controls by asking the agent to write a policy for you. Your policy should have at least one rule that requires Human-in-the-Loop or denies a specific action.

   For example, if you’re using Linear, try a prompt like this:

   Help me set up a Keycard policy for the Linear MCP server. Allow me to read issues and require In-the-Loop approval for saving and updating issues.

   Claude may trigger an initial connection to Linear via Keycard. You’ll be prompted to authorize access between Keycard and Linear:

   

   Default policies require your approval. You will see Keycard ITL Prompt like this:

   

   Claude proposes a policy written in the Cedar policy language for you to review. It might look something like this:

   @description("Allow get and list.")
   permit (principal, action == Action::"Agent::ToolUse", resource)
   when { resource like Tool::"mcp__linear__get_*" || resource like Tool::"mcp__linear__list_*" };
   
   @description("Require in-the-loop prompt for saving new issues and updating.")
   @itl("prompt")
   permit (principal, action == Action::"Agent::ToolUse", resource)
   when { resource like Tool::"mcp__linear__save_issue_*"
       || resource like Tool::"mcp__linear__update_*" };

   Type yes to apply it. Claude writes the policy to your Keycard state directory and confirms it’s active. The exact tool names will match what your installed MCP server actually exposes.

7. Trigger an action governed by your policy

   Ask Claude to complete a task the policy now gates or forbids:

   Create a new issue.

   The Keycard hook intercepts the tool call before it runs and prompts you for approval:

   

   Claude uses the /keycard-query-policy skill to explain what happened.

8. Check the session log

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

Now that you have Claude Code running in a secure session with token exchange and policy governance, 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 Apps Without Static Secrets so workloads authorize every call with their own identity instead of long-lived API keys
• Grant Agent Access to APIs so autonomous agents get their own scoped identity and audit trail, independent of any human

Why am I being prompted each time?

• The default policy at ~/.local/state/keycard/policy.cedar configures Bash, Edit, and Write actions to require ITL approval these are the tools most commonly used during development.
• To reduce prompts, ask Claude to update your policy with more permissive rules for actions you trust.

keycard run fails to start

• Verify keycard auth signin succeeded by running keycard whoami
• Check that keycard.toml exists in the project root with a valid [zone] id = "<your-zone-id>"
• Confirm the zone ID matches what you used for signin

The policy isn’t blocking what I expect

• Ask Claude: “What’s my current policy?” to trigger /keycard-query-policy and see the active rules
• Make sure the Cedar diff included a forbid clause, or that the tool was simply omitted from any permit clause (allow-list policies deny by omission)
• Restart keycard run -- claude after editing the policy if the change isn’t picked up

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
• Check that your zone’s identity provider is configured (Console → Identity Providers)