Getting Started MCP

MCP server that reads GitHub and Linear on your behalf using short-lived tokens from Keycard for each call.

Run it locally, connect Claude Code, and reads will appear in the Keycard console under your name.

What the MCP tools show you

whoami answers as you, reading claims from your Keycard zone. At startup the server authenticates as itself with the credential in .env and reads the claims of the token Keycard issues it. That issuance appears in the Keycard console with the application as the subject, rather than you.

list_pull_requests returns your open pull requests. The server asks Keycard for a token scoped to you, spends it on GitHub's hosted MCP server, and discards it. This call appears in the Keycard console with you as the subject, rather than the application.

list_tickets returns your assigned Linear tickets, newest activity first. It uses a token scoped to you on Linear's hosted MCP server, just like the GitHub tool.

Related MCP server: GitHub MCP Connector

Prerequisites

You need Python 3.12 or later, uv, and a Keycard account.

Quickstart

1. Clone the project and move into it.

   git clone https://github.com/keycardai/getting-started-mcp local-tools
   cd local-tools

2. Install the Keycard CLI and enroll the project.

   brew install keycardai/tap/keycard
   keycard new mcp

   keycard new mcp creates the local-tools application in your zone, mints a credential for local development, and writes .env.

3. Install dependencies and start the server.

   make install
   make dev

   The server listens on http://localhost:8181/mcp. Open Activity in the Keycard console and you'll see the startup whoami call attributed to local-tools.

4. Add GitHub as a dependency of the application.

   In the console: go to Dependencies, choose Add Dependency, then Add Resource, and pick GitHub MCP. Keycard walks you through connecting GitHub and then holds tokens for you.

   To use list_tickets, add Linear as a dependency the same way.

5. Connect Claude Code.

   claude mcp add --transport http --scope local local-tools http://localhost:8181/mcp
   claude

6. Ask Claude Code to list open pull requests. You sign in, consent to using GitHub, and the read comes back. Activity records the grant and the read with you as the subject.

How the authorization works

Two exchanges, and neither one puts a GitHub credential in this repository.

At startup the server authenticates to your Keycard zone with its own client ID and secret from .env, a plain OAuth client credentials grant, and reads the claims of the token it is issued. UserInfo is a user endpoint and does not accept an application as its subject, so the server shows its own token rather than calling UserInfo as itself.

To list pull requests the server hands the caller's token to Keycard using RFC 8693 token exchange to get back a token scoped to the request. Keycard decides whether to issue the token by ensuring the resource is a dependency of the application and that you consented to the use. The token comes back scoped to one resource and the server throws it away after the call.

So .env holds exactly one secret: the application's own. GitHub's credential lives in Keycard, and nothing in this project can read it.

Configuration

Every value comes from .env, which is written by keycard new mcp and loaded at startup.

The server runs without KEYCARD_CLIENT_ID and KEYCARD_CLIENT_SECRET, so you can start it before you enroll. It logs a warning and skips the startup call.

On Vercel the server does not announce itself, which is why KEYCARD_STARTUP_IDENTITY_CHECK stays off there. The platform's OIDC token arrives per request (x-vercel-oidc-token) rather than with the process, so a startup hook has nothing to present. The deployed server uses that token to authenticate each tool call's token exchange, and the deployment shows up in Activity through the first real call.

Commands

Run make to see the list.

make env-push sends KEYCARD_ZONE_URL from .env to the linked Vercel project. It does not send KEYCARD_CLIENT_ID or KEYCARD_CLIENT_SECRET. The deployed server authenticates with Vercel's workload identity. Redeploy after it runs.

Project layout

Deploying

Fly.io

Run these commands from this project's folder after enrolling it locally:

brew install flyctl
fly auth login
fly launch --no-deploy
fly secrets set --stage KEYCARD_ZONE_URL="$(grep ^KEYCARD_ZONE_URL= .env | cut -d= -f2-)"
fly ips allocate-v4 --shared
fly ips allocate-v6
fly machine run . --name local-tools --port 443:8181/tcp:tls:http --port 80:8181/tcp:http --restart always

Use the included fly.toml when prompted. fly launch writes the app name into it; choose your organization in its settings. Skip an IP allocation if fly ips list already shows that address type. The named Machine serves HTTP continuously, not on a schedule. Don't use fly deploy: it creates Machines with generated names instead of the identity you register next.

In the Console guide's Deploy step, choose Fly and submit the organization slug, app name, Machine name (local-tools), and deployed URL (https://<app-name>.fly.dev). For a personal organization, use your account slug from fly.io/dashboard/<slug>, not the personal alias shown by fly orgs list. Keycard adds a Fly OIDC Provider, a Workload Identity credential scoped to that Machine, and the deployed /mcp Resource to your enrolled Application.

The server obtains fresh Fly identity tokens from the SDK's FlyTokenSource over /.fly/api. The client ID and secret stay local. MCP_SERVER_URL defaults to https://<app-name>.fly.dev/mcp; for a custom domain, set that variable on Fly and use the same URL in the form. The startup identity check is off on Fly so the server starts before you register it. Its first tool call is the proof of the deployed identity.

Add the deployed /mcp URL to your coding agent, then call a tool. The exchange appears under Activity with your delegated identity and the server's Fly workload credential. The Fly walkthrough covers these steps in detail.

Vercel

We're still building the Vercel path, and the production credential handling remains unfinished. Run vercel deploy, then give the console your Vercel team slug, project name, and the deployed URL. Keycard creates a provider for your team, registers the deployed endpoint, and issues a workload identity credential keyed to it.

The deployed server holds no secret at all. Vercel mints a short-lived OIDC token for every function invocation, Keycard trusts your team's issuer, and the exchange happens against that. The client ID and secret in .env stay local.

The deployed server does not announce an identity of its own. Each tool call authenticates its token exchange with the workload identity, so the deployment shows up on the Activity feed through the first real call rather than through a separate self-issued announcement.

Troubleshooting

If startup fails with KEYCARD_ZONE_URL is not set, you haven't run keycard new mcp yet.

If the log says no application credential was found, you haven't run keycard new mcp yet. The server still serves; only the startup identity call is skipped.

If a GitHub tool returns a token exchange error, GitHub isn't a dependency of the application yet, or you haven't consented to this agent using it. Both are fixed in the console under Dependencies.

If your agent can't connect, check that MCP_SERVER_URL matches the URL you gave it, including the /mcp path. Keycard pins the token audience to that value, so a mismatch shows up as a rejected token.

License

Apache-2.0 — see LICENSE and, for the copyright notice, NOTICE. The Keycard name and logo are trademarks; TRADEMARKS.md states how they may be used.