Keypup's MCP server is currently in beta. The capabilities exposed on the MCP server will be continuously expanded during this phase. Do not hesitate to contact our team via chat to submit your use cases and provide feedback.
The Keypup MCP (Model Context Protocol) server lets you plug your Keypup engineering analytics directly into an AI assistant (Claude, Cursor, Kiro, ChatGPT desktop, and any other MCP-compatible client).
Once connected, you can ask questions about your engineering activity in plain language and let the AI build and run the underlying reporting queries for you.
Unlike the GraphQL API, which is designed for developers writing application code, the MCP server is designed to be driven conversationally by an AI on your behalf. No query language to learn, no code to write.
1. What the MCP server can do
The MCP server exposes a focused set of tools that let an AI explore and query your Keypup data:
Discover your companies — list the companies (teams) you belong to.
Explore datasets — browse the available datasets (issues & pull requests, commits, comments, reviews, activity events) and the fields each one exposes.
Discover formula operators — list the functions and operators available when building metrics, dimensions, and filters.
Run reporting queries — execute aggregated queries against any dataset, with metrics, dimensions (group-by), filters, sorting, and pagination.
Generate a query from natural language — turn a plain-language request into a ready-to-run structured query, which the AI can then execute.
The AI orchestrates these tools automatically. A typical flow looks like:
List your companies
Pick the relevant dataset
Look up the fields it needs
Build the query
Run it
Summarize the results
You only ask the question.
2. The kinds of questions you can ask
Once the Keypup MCP server is connected, you can ask your AI assistant questions such as:
Delivery & throughput
"How many pull requests did we merge each month over the last 6 months?"
"What's our weekly issue closing rate this quarter?"
"How many commits were made per author last month?"
Cycle time & performance
"What's the average time between PR creation and merge over the last 12 weeks?"
"Show me the review turnaround time trend for the last 3 months."
"Which repositories have the slowest cycle time?"
Quality & process
"How many bugs were raised vs. closed each week this quarter?"
"What proportion of our pull requests resolve at least one issue?"
"How many PRs were merged without a review?"
Workload & collaboration
"Who are our most active reviewers this month?"
"How is work distributed across the team right now?"
"How many comments do our pull requests receive on average?"
Open-ended exploration
"Summarize our engineering activity over the last month."
"Compare open vs. closed issues over time."
"What labels are most common on our issues?"
The AI will pick the right dataset, build the appropriate metrics and filters, run the query, and explain the results. You can refine iteratively ("now break that down by repository", "restrict it to the backend team", etc.).
3. Authentication options
The Keypup MCP server is available at:
https://hq.keypup.io/mcp
It uses the streamable HTTP transport and supports two ways to authenticate:
OAuth 2.1 (recommended): your client is already whitelisted by our team (e.g., Kiro, Cursor) or registers itself automatically through a Client ID Metadata Document "CIMD" (e.g., VS Code, Claude). Access is authorized through your browser, and there is no token to copy, store, or rotate.
API token: a Keypup API token passed in the
Authorizationheader. Use this for any client that does not support OAuth dynamic client registration.
The next section covers the API token method (works with every client). The client-specific sections that follow show the one-click and OAuth setup for each supported assistant.
4. Standard installation using an API token
This method works with every MCP client. Most clients are configured through a JSON file (for example, VS Code, Kiro, and Claude Desktop use an mcp.json-style configuration).
4.1 Generating an API token
The MCP server authenticates with the same API tokens used by the GraphQL API.
Go to Settings > Account and open the API Token tab.
Click Create token.
Set a descriptive name (e.g., "MCP - Claude Desktop") and an expiration. We strongly recommend setting an expiration.
Select the token scopes (permissions).
Get started quickly: select
mcp:readandmcp:writeOr use fine-grained access: select
hq:companies:readat the very least, then any API scope relevant to the resources you are planning to use in your AI work.
Click Create. The token is shown only once and can be copied for 1 minute.
4.2 Setting up your client
Add a keypup server entry pointing at the endpoint, with your API token in the Authorization header:
{
"mcpServers": {
"keypup": {
"url": "https://hq.keypup.io/mcp",
"headers": {
"Authorization": "Bearer my_keypup_api_token"
}
}
}
}
A few notes:
Replace
my_keypup_api_tokenwith the token you generate in section 5. Keep theBearerprefix.The server name (
keypup) is arbitrary - name it however you like.
Once saved, restart or reconnect the MCP server in your client. The Keypup tools should appear in the client's tool list, and you can start asking questions.
5. Install in: VS Code
VS Code supports OAuth with dynamic client registration (CIMD). Add a new MCP server in VS Code and enter the server URL when prompted:
https://hq.keypup.io/mcp
VS Code registers itself and opens a browser window to sign in to Keypup and authorize access.
Alternatively, you may also configure the Keypup MCP server via JSON:
{
"servers": {
"keypup": {
"type": "http",
"url": "https://hq.keypup.io/mcp"
}
}
}To use an API token instead, add a headers block as described in section 4.
6. Install in: Cursor
Add a keypup entry to Cursor's mcp.json. The auth.CLIENT_ID field enables OAuth via dynamic client registration:
{
"mcpServers": {
"keypup": {
"url": "https://hq.keypup.io/mcp",
"auth": {
"CLIENT_ID": "https://cursor.com"
}
}
}
}On first connection, Cursor opens a browser window to sign in to Keypup and authorize access.
To use an API token instead, replace the auth block with a headers block as described in section 4.
7. Install in: Kiro
Add a keypup entry to Kiro's mcp.json. The oauth block enables OAuth via dynamic client registration:
{
"mcpServers": {
"keypup": {
"url": "https://hq.keypup.io/mcp",
"oauth": {
"clientId": "https://kiro.dev",
"redirectUri": "127.0.0.1:57517"
}
}
}
}On first connection, Kiro opens a browser window to sign in to Keypup and authorize access.
To use an API token instead, replace the oauth block with a headers block as described in section 4.
8. Install in: ChatGPT
A dedicated Keypup app for ChatGPT is coming soon.
9. Install in: Claude & Claude Code
Claude and Claude Code support OAuth with dynamic client registration (CIMD). Simply add a custom connector / MCP server and enter the server URL:
https://hq.keypup.io/mcp
Claude opens a browser window to sign in to Keypup and authorize access, and then the Keypup tools become available.
10. Security considerations
OAuth is the recommended method: it issues scoped, browser-authorized access without a long-lived credential to manage.
If you use an API token, treat it like a password. Anyone holding it can query your Keypup data within the granted scopes.
Prefer short-lived tokens with an expiration, and rotate them periodically.
Keep tokens out of shared or version-controlled files. Store them only in your MCP client's local configuration.
All Keypup MCP tools are read-only — they never modify your data — but the underlying token may carry broader scopes if you grant them, so stick to the minimal recommended scopes.