MCP Server
The Cograph MCP server exposes your knowledge graph to any AI assistant that supports the Model Context Protocol — Claude, GPT-4, Gemini, and others. Ask natural language questions about your organization and get structured answers back.
Installation
The MCP server runs as a local process on your machine and connects to the Cograph API using your API key. It's distributed as an npm package and works with any MCP-compatible client.
Generate an API key
Go to Settings → API Keys in your Cograph dashboard and create a new key. Choose read-only for most agents, or read+write if you want your AI to create knowledge capture tasks.
Install the MCP server
Choose your client below and add the configuration. The server is distributed as an npm package and runs locally on your machine.
Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"cograph": {
"command": "npx",
"args": ["-y", "@cograph/mcp@latest"],
"env": {
"COGRAPH_API_KEY": "cograph_sk_your_api_key_here"
}
}
}
}Restart your AI client
Restart Claude Desktop, VS Code, or your MCP client. The Cograph tools will appear automatically once the server connects.
Test the connection
Ask your AI: "Use the query_expertise tool to find what {your email} knows." You should see your expertise profile returned.
Authentication
Generate an API key from Settings → API Keys. Choose your scope:
cograph_sk_ro_Access all 6 read-only tools and 3 resources. Safe for general AI assistant use. Recommended for most use cases.
cograph_sk_rw_Enables the create_knowledge_item tool. Rate limited to 10 write operations per minute. Use when you want your AI to create capture tasks.
# Read-only key — safe for most AI workflows
COGRAPH_API_KEY=cograph_sk_ro_xxxxxxxxxxxxxxxx
# Read+write key — needed for create_knowledge_item
COGRAPH_API_KEY=cograph_sk_rw_xxxxxxxxxxxxxxxxTip: API keys are per-user. Each team member should generate their own key. Keys are scoped to your organization automatically — there's no risk of leaking another org's data even if a key is compromised.
Tools Reference
Tools are callable actions. Your AI can call them with specific inputs and gets structured results back. All tools are scoped to your organization automatically — you never need to provide an org ID.
query_expertisereadReturns the full expertise profile for an employee — topics, scores, and evidence from code, docs, and communication.
employee (email or name)“What does sarah@company.com know? Use query_expertise to build her profile.”
find_knowledge_gapsreadIdentifies topics at risk in the organization — areas with active departures and topics where only one person holds the knowledge.
includeActiveRisks (bool)includeSinglePointsOfFailure (bool)minExpertiseScore (0–1)“Use find_knowledge_gaps to find our top 5 single points of failure.”
identify_successorsreadFinds the best candidates to receive knowledge transfer for a specific topic, ranked by expertise overlap and collaboration history.
topic (string)departingEmployee (email or name)limit (1–10)“Use identify_successors to find who should take over John's database responsibilities.”
search_knowledgereadFull-text search across all connected data: employees, knowledge items, Slack messages, GitHub commits, and risk reports.
query (natural language)contentTypes (optional)limit (1–20)“Search for all documentation we have about our authentication system.”
get_collaboration_networkreadReturns top collaborators for an employee with strength percentages and contexts — who they pair with on code, docs, and discussions.
employee (email or name)limit (1–25)“Use get_collaboration_network to show who Alice works most closely with.”
simulate_departure_impactreadModels the organizational impact of all current active departures at once. Shows topics affected and sole experts at risk.
(none — uses active departures)“Use simulate_departure_impact to show me the risk from our current departures.”
create_knowledge_itemwriteCreates a knowledge capture task for a departure. Requires write scope on your API key.
departureIdtitledescriptiontypepriorityknowledgeArea“Create a high-priority knowledge item for John's departure about the payments API.”
Resources
Resources are read-only data endpoints identified by a URI. Your AI can fetch them like web pages and receive structured JSON.
cograph://employees/{email}/knowledge-profileStructured JSON profile for any employee: expertise topics with scores, top collaborators, and evidence sources.
cograph://employees/sarah@company.com/knowledge-profilecograph://departures/{id}/risk-reportFull risk assessment for a departure: overall score, knowledge items by priority, and capture progress.
cograph://departures/dep_abc123/risk-reportcograph://org/bus-factor-analysisOrganization-wide single points of failure: topics and employees where knowledge is concentrated in one person.
cograph://org/bus-factor-analysisPrompts
Prompts are pre-built multi-step workflows. Instead of calling tools one by one, you invoke a prompt and your AI orchestrates all the required tool calls and produces a structured output.
offboarding-kickoffGenerates a comprehensive offboarding briefing for a departing employee. Orchestrates three tools to produce an executive-ready summary with capture plan and timeline.
knowledge-transfer-interviewRuns a structured, interactive knowledge extraction session with the departing employee. Generates targeted questions from their expertise profile and offers to capture answers as knowledge items.
successor-briefingCreates a personalized onboarding plan for the successor, showing exactly what they need to learn, key people to meet, and a 30-day action plan based on both people's expertise profiles.
Example Conversations
Copy these prompts directly into Claude Desktop, VS Code Copilot, or any MCP-compatible AI. Click any card to copy to your clipboard.
Use query_expertise to find everything sarah@company.com knows.
Get a full expertise profile for any employee
Search for all documentation we have about our authentication system.
Full-text search across all connected data sources
Who are our top experts on Kubernetes? Use find_knowledge_gaps to check if there's a single point of failure.
Identify expertise concentration risks
Use get_collaboration_network to show me who alex@company.com works most closely with and in what contexts.
Map collaboration patterns and dependencies
Run the offboarding-kickoff prompt for john.smith@company.com.
Generate a comprehensive offboarding briefing
Run the knowledge-transfer-interview prompt for maria@company.com with departure ID dep_abc123, focusing on the payments infrastructure topic.
Start a structured knowledge extraction session
Run the successor-briefing prompt for the new hire (newhire@company.com) replacing the departing employee (departing@company.com). Focus on authentication, database design, and API patterns.
Create a personalized onboarding plan for the successor
Use simulate_departure_impact to show me the organizational impact of our current active departures.
Model the risk of all pending departures at once
Use find_knowledge_gaps to find all knowledge areas where we have a single point of failure. Who are our key people?
Discover your organizational bus factor risks
Fetch the resource cograph://org/bus-factor-analysis and summarize the critical risks.
Get a structured bus factor report
Use identify_successors to find the 5 best people to take over the "payment processing" knowledge from departing@company.com.
Find the best candidates for knowledge transfer
Compare the expertise of alice@company.com and bob@company.com. Who has more overlap with the departing employee carol@company.com?
Compare candidates for knowledge transfer fit