@agekey/mcp-server

AgeKey MCP Server - Manage AgeKey applications directly from your AI IDE.

Features

• 🔐 Clerk OAuth Authentication — Seamless login via browser
• 🏢 Multi-Organization Support — Access all your organizations
• 📱 Application Management — Create, list, and manage apps
• 🔑 Credentials — Get and rotate test/live credentials
• 🔗 Redirect URIs — Add and remove callback URLs
• 🛡️ RBAC — Role-based access control (Member → test, Admin → live)
• 🔧 Utilities — JWT decoder, error explainer, code samples

Installation

Cursor IDE

Add to your MCP config (.cursor/mcp.json):

{
  "mcpServers": {
    "agekey": {
      "command": "npx",
      "args": ["-y", "@agekey/mcp-server"]
    }
  }
}

Claude Desktop

Add to your config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "agekey": {
      "command": "npx",
      "args": ["-y", "@agekey/mcp-server"]
    }
  }
}

Authentication

On first use, the MCP server will:

1. Open your browser to the AgeKey login page
2. You authenticate with Clerk (existing AgeKey account)
3. Token is stored locally in ~/.agekey/session.json

No manual token management needed!

The server connects to the production AgeKey Developer Portal by default. Environment configuration (staging, dev, local) is for internal use only and is not documented here.

Available Tools

Organizations

| Tool | Description | |------|-------------| | list_organizations | List all organizations you have access to |

Applications

| Tool | Description | |------|-------------| | list_applications | List apps in an organization | | get_application | Get app details | | create_application | Create a new app (Member+) |

Credentials

| Tool | Description | |------|-------------| | get_credentials | Get test or live credentials | | rotate_credentials | Rotate credentials (test: Member+, live: Admin+ with confirmation) |

Redirect URIs

| Tool | Description | |------|-------------| | add_redirect_uri | Add a callback URI | | remove_redirect_uri | Remove a callback URI |

Utilities

| Tool | Description | |------|-------------| | decode_jwt | Decode and explain an AgeKey JWT | | explain_error | Get help for OIDC error codes | | get_code_sample | Get integration code in TypeScript/Python/Go/Java |

RBAC Permissions

| Role | Test Mode | Live Mode | |------|-----------|-----------| | Viewer | Read only | Read only | | Member | Full access | Read only | | Admin | Full access | Full access ⚠️ | | Owner | Full access | Full access ⚠️ |

⚠️ Live mode operations require explicit confirmation phrases.

Example Usage

You: "List my AgeKey organizations"

Claude: You have access to 2 organizations:
1. Acme Corp (Owner) - 3 applications
2. Side Project (Admin) - 1 application

You: "Create a new app called 'My Game' in Acme Corp"

Claude: ✅ Created application "My Game"

Test Credentials:
- App ID: ak_test_abc123...
- Secret: sk_test_xyz789... ⚠️ Save this!

Next steps:
1. Add a redirect URI: http://localhost:3000/callback
2. Try it in the sandbox

You: "Rotate live credentials for My Game"

Claude: ⚠️ WARNING: This will rotate LIVE credentials!

To proceed, confirm: "ROTATE LIVE CREDENTIALS"

You: "ROTATE LIVE CREDENTIALS"

Claude: ✅ Live credentials rotated
🚨 Update your production environment NOW!

Development

# Install dependencies
pnpm install

# Build
pnpm build

# Run (connects to production portal)
node dist/index.js

License

MIT