MCP integration

Connect Karma to your AI app

Karma exposes an OAuth-protected MCP server so AI apps like Cursor, Claude Desktop, and Codex can read your projects, grants, and impact data — and act on your behalf when you allow them to.

MCP server URL

https://gapstagapi.karmahq.xyz/mcp

Most AI apps will discover everything else automatically. You'll be asked to sign in to Karma and approve access the first time you connect.

How to connect

  1. Copy the MCP server URL

    Grab the URL from your Karma settings page or this guide.

  2. Add it to your AI app

    In Cursor, Claude Desktop, or your MCP client of choice, add the URL as a remote server.

  3. Sign in to Karma

    The first time you connect, your AI app will open Karma in your browser to approve access.

  4. Start working

    Ask the agent to summarize a project, list pending milestones, or draft an application.

Supported apps

  • Cursor

    Docs ↗

    Cursor's MCP integration discovers OAuth-protected servers automatically.

    Settings → MCP → Add Server. Paste the URL above. Cursor will open Karma in your browser to sign in.

  • Claude Desktop

    Docs ↗

    Claude Desktop supports remote MCP servers via the OAuth handshake.

    Settings → Developer → Add Server. Choose 'Remote URL' and paste the URL above.

  • Codex CLI

    Docs ↗

    OpenAI's Codex CLI supports remote MCP servers via OAuth.

    Runcodex mcp add karma --url https://gapstagapi.karmahq.xyz/mcpand follow the browser prompt.

  • Other MCP clients

    Any MCP-spec-compliant client (2025-11-25+) auto-discovers the OAuth flow.

    Add the URL as a remote server. The client will follow the WWW-Authenticate hint and walk you through Karma's sign-in flow.

Frequently asked questions

Which AI apps can connect to Karma?
Cursor, Claude Desktop, Codex CLI, and any MCP-spec-compliant client (2025-11-25 or later).
Does it cost anything to use the MCP server?
No. The Karma MCP server is free for individual builders and program admins.
What data can an AI agent see?
Public project and grant data without sign-in. With OAuth, an agent sees what your Karma account can see — your projects, programs you administer, and applications you review.
How does authentication work?
Standard OAuth 2.0 with bearer tokens. AI apps walk you through Karma sign-in in your browser the first time you connect. RFC 9728 and RFC 6750 compliant.
Can I use an API key instead of OAuth?
Yes. Generate one in your Karma settings and pass it as the x-api-key header. Useful for headless agents and scripts.
What MCP protocol version is supported?
Protocol version 2025-11-25 and later.