Documentation
Everything you need to get started, integrate, and get the most out of Topogy.
Topogy MCP Server
The Topogy MCP server lets your own AI assistant — such as Claude Code, OpenAI Codex, GitHub Copilot in VS Code or Gemini CLI — answer questions about your organization's AI usage and engineering output. Ask in plain language ("How did AI adoption change by team this quarter?", "Which teams spent the most per merged PR last month?") and your assistant pulls the numbers from Topogy and reasons over them for you.
Topogy never sees your question. Your assistant asks Topogy for well-defined measures, and every number comes back with its definition, unit, data sources, freshness and any known coverage gaps, so the assistant can explain what it's showing you.
Who can use it
- Organization admins. The MCP server is available to people with the Admin role in your Topogy organization. Anyone else who connects is asked to contact an admin.
- MCP enabled for your organization. If your assistant reports "MCP access is not enabled for your account", ask your Topogy contact to turn it on.
You sign in with the same account you use for the Topogy app, including Okta SSO.
Install
The server URL is:
https://mcp.topogy.com/mcpClaude Code
- Add the server once, for every project:
claude mcp add --transport http --scope user topogy https://mcp.topogy.com/mcp- In Claude Code, run
/mcp, select topogy, and choose Authenticate. Your browser opens a consent page; approve it and sign in to Topogy. - Back in Claude Code,
/mcplists topogy as connected. Start asking questions.
--scope user makes the server available in every project on your machine. Leave it out to add it to the current project only.
Claude Desktop and claude.ai
- Go to Settings → Connectors and choose Add custom connector.
- Name it Topogy and enter
https://mcp.topogy.com/mcpas the URL. - Select Connect, approve the consent page and sign in to Topogy.
On Claude Team and Enterprise plans, an organization owner can add the connector once for the whole organization; each person still signs in with their own Topogy account.
Other MCP clients
Any assistant that supports remote MCP servers over HTTP with OAuth sign-in can connect, including OpenAI Codex, GitHub Copilot in VS Code and Gemini CLI. Add https://mcp.topogy.com/mcp as a remote (HTTP) MCP server following your client's documentation, then sign in to Topogy when it opens the consent page.
Once connected, you stay signed in for up to 30 days before your assistant asks you to sign in again.
What you can ask about
Your assistant can see:
- The measures below, each with its definition and the ways it can be broken down.
- Your team structure, so it can compare teams or drill into one team's sub-teams.
- The AI tools and models your organization has used.
- Session purposes and work types — what AI sessions were for (for example, building features versus fixing bugs).
- Session tags your developers attach to their sessions, such as a project or ticket.
- How fresh each data source is, and when its history begins.
Any measure can be returned week by week or as a total for a period, filtered or grouped by the dimensions it supports, sorted to find the top or bottom of a ranking, and compared against your whole organization. Weeks follow your organization's week definition.
Measures
AI usage
| Measure | What it is | Break down by |
|---|---|---|
| Sessions | Runs of an AI tool that made at least one request | tool, model, purpose, work type, tag, team, person |
| Sessions in use | Sessions that made at least one request in the period, whenever they started | tool, model, tag, team, person |
| Active session time | Hands-on time spent in sessions | tool, model, purpose, work type, tag, team, person |
| Requests | Completed model calls | tool, model, purpose, work type, tag, team, person |
| Turns | Prompts people entered | tool, model, purpose, work type, tag, team, person |
| Tokens | All input and output tokens | tool, model, purpose, work type, tag, team, person |
| Cache rate | Share of input tokens served from the cache | tool, model, purpose, work type, tag, team, person |
| Consumed Amount | AI usage valued at each model's list price | tool, model, purpose, work type, tag, team, person |
| Billed Amount | What your company was billed for AI, where billing data is available | tool, team, person |
Adoption
| Measure | What it is | Break down by |
|---|---|---|
| Engineers | People who merged a pull request or used an AI coding tool | team |
| AI Adoption | Share of engineers who used an AI coding tool | team |
| Active AI users | Share of people with any AI usage, from any product | team |
Engineering output
| Measure | What it is | Break down by |
|---|---|---|
| Merged PRs | Pull requests merged in the period | team, person |
| AI-Assisted PRs | Merged PRs with evidence that AI helped write them, with examples | team, person |
| Consumed Amount per Merged PR | AI coding spend divided by merged PRs | team, person |
| Lines changed | Lines added plus lines deleted in merged PRs | team, person |
| Cycle time | Median time from a PR being opened to merged | team, person |
| Time to first review | Median time from a PR being opened to its first review | team, person |
| Tickets resolved | Work items moved to done or cancelled | team, person |
| Bugs filed | Bug or defect work items created | team, person |
| Bugs fixed | Bug or defect work items moved to done | team, person |
What's available depends on the integrations you've connected: AI usage measures need Claude Code telemetry or Claude Enterprise, pull request measures need GitHub, and ticket measures need Linear or Jira.
Time ranges
Most measures cover up to two years at a time. Requests, Turns, Tokens, Cache rate, Engineers, AI Adoption and Active AI users cover up to the most recent 90 days. Your assistant is told each measure's limits, so it picks a range that fits.
Reading the numbers
- Every value comes with its definition. A figure can differ slightly from a similar-looking one in the Topogy app when the two count different things, so compare definitions before comparing numbers.
- Team figures include each team's sub-teams, use current team membership, and count people only — bot and AI-agent activity counts toward your organization's totals but not toward any team or person.
- AI-Assisted PRs is a floor: it counts only PRs with evidence Topogy can detect.
- Each measure's known coverage gaps travel with its numbers, and your assistant can pass them on when they matter.
Troubleshooting
Your assistant says MCP access is not enabled. MCP isn't turned on for your organization yet. Ask your Topogy contact.
Your assistant says Topogy MCP is available to organization admins. Your account doesn't have the Admin role. Ask an admin in your organization for access.
Sign-in keeps failing. Sign in to the Topogy app with the same account first to confirm it works, then authenticate again from /mcp in Claude Code or the connector settings in Claude.
Numbers look lower than expected. Ask your assistant which data sources the measure uses and how fresh they are. A source that isn't connected, or a recent day still being processed, shows up there.
For help, reach out to your Topogy contact or email support@topogy.com.