The Cogniscape MCP is a read-only server that exposes your Cogniscape knowledge graph to AI assistants via the Model Context Protocol. It provides seven tools for querying development activity, entities, relationships, lifecycle timelines, and AI costs — plus six built-in prompts for common workflows.
Any MCP-compatible client can connect: Claude Code, Claude Desktop, OpenAI Codex, Cursor, and others.
Transport
The Cogniscape MCP uses Streamable HTTP as its transport. Every request must include your customer key as a query parameter: ?customer_key=YOUR_KEY. This is how the server resolves your tenant and isolates your data.
Clients that support Streamable HTTP natively — such as Claude Code, Claude Desktop, OpenAI Codex, and Cursor — can connect directly. For clients that only support stdio, use mcp-remote as a bridge.
The Cogniscape MCP exposes seven tools that AI assistants can call to retrieve data from your knowledge graph.
get_activity_timeline
The primary tool for understanding what happened. Returns entities (PRs, issues, features, developers) that were active during a time period, along with their summaries and temporally-scoped facts.
| Parameter | Type | Default | Description |
|---|
since | string | "24h" | Time period — ISO-8601 datetime or relative (7d, 24h, 2w) |
source | string | all | Filter by data source: agent, github, or linear |
repository | string | all | Filter by repository (e.g. org/repo) |
group_id | string | tenant-wide | Scope to a specific namespace |
max_items | int | all | Maximum number of entities to return |
search_nodes
Semantic search for entities (nodes) in the knowledge graph — developers, repositories, PRs, issues, features, and any other concept Cogniscape has extracted.
| Parameter | Type | Default | Description |
|---|
query | string | required | Natural language search query |
num_results | int | 10 | Maximum number of entities to return |
group_id | string | tenant-wide | Scope to a specific namespace |
search_facts
Semantic search for relationships (edges) between entities. Facts include temporal validity — you can see when a relationship was true and when it expired.
| Parameter | Type | Default | Description |
|---|
query | string | required | Natural language search query |
num_results | int | 10 | Maximum number of facts to return |
group_id | string | tenant-wide | Scope to a specific namespace |
since | string | — | Filter facts created at or after this date (ISO-8601) |
until | string | — | Filter facts created at or before this date (ISO-8601) |
since for temporal filtering).
get_episodes
Retrieves raw ingestion events — the conversations, code changes, and webhook payloads that were added to the graph. Useful for understanding provenance and context.
| Parameter | Type | Default | Description |
|---|
group_id | string | tenant-wide | Scope to a specific namespace |
max_episodes | int | 10 | Maximum number of episodes to return |
reference_time | string | now | ISO-8601 timestamp to anchor the query |
get_token_usage
Returns AI token consumption and estimated cost in USD, broken down by model and developer.
| Parameter | Type | Default | Description |
|---|
period | string | "week" | Predefined period: today, week, or month |
developer | string | all | Filter by developer name |
date_start | string | — | Custom start date (YYYY-MM-DD, inclusive) |
date_end | string | — | Custom end date (YYYY-MM-DD, inclusive) |
repository | string | all | Filter by repository name |
When date_start and date_end are provided, the period parameter is ignored.
get_developer_roi
Returns ROI analysis per developer: total cost, daily average, daily trend, and breakdowns by model and repository.
| Parameter | Type | Default | Description |
|---|
developer | string | all | Filter by developer name |
period | string | "month" | Predefined period: today, week, or month |
date_start | string | — | Custom start date (YYYY-MM-DD, inclusive) |
date_end | string | — | Custom end date (YYYY-MM-DD, inclusive) |
repository | string | all | Filter by repository name |
get_saga_timeline
Retrieves the ordered timeline of episodes belonging to a lifecycle saga. Sagas automatically group related events — every PR, issue, and coding session gets its own saga, linking all events in chronological order.
| Parameter | Type | Default | Description |
|---|
saga_name | string | required | The saga identifier (e.g. "PR #99 cogniscape-app", "Issue #42 cogniscape-app", "Session sess-abc-123") |
group_id | string | tenant-wide | Scope to a specific namespace |
| Event type | Saga name format |
|---|
| Pull request events | PR #<number> <repository> |
| Issue events | Issue #<number> <repository> |
| Coding session events | Session <session_id> |
Prompts
The Cogniscape MCP includes six built-in prompts — pre-written conversation starters that guide the AI assistant to use the right tools and present results in a structured way. These appear as suggested prompts in compatible clients.
daily_standup
Summarizes the last 24 hours of activity: what was done, what’s in progress, and attention points. Accepts optional repository and developer filters.
weekly_review
Generates a comprehensive weekly report: deliveries, merged PRs, deployments, decisions, and blockers. Designed for team review meetings.
developer_profile
Shows a developer’s activity profile: recent contributions, repositories, contribution types (code, reviews, issues), and AI token consumption.
document_history
Shows the change history for a specific document, repository, or component: who modified it, when, and what changed.
cost_report
Generates an AI cost report for a given period using get_token_usage and get_developer_roi. Includes total estimated cost, distribution by model and developer, daily trend, and average daily cost. Presented for non-technical managers.
team_overview
Maps the project’s contributors: areas of expertise, contribution types (code, reviews, management), and recent activity. Presented as a team map.
Not sure which tool to use? Here’s a quick reference:
| Question type | Recommended tool |
|---|
| ”What happened this week?” | get_activity_timeline |
| ”Who is this developer?” | search_nodes → search_facts |
| ”What PRs did Alice merge?” | search_facts |
| ”What was authored this week?” | search_facts with since |
| ”Show me PR #99 full history” | get_saga_timeline |
| ”How much did Claude cost?” | get_token_usage |
| ”Show me ROI by developer” | get_developer_roi |
| ”When was this data ingested?” | get_episodes |
| Broad time-based questions | get_activity_timeline |
| Lifecycle tracking (PR/issue) | get_saga_timeline |
| Entity lookup + relationships | search_nodes → search_facts |
For complex questions, the AI assistant will combine multiple tools automatically. For example, “what did Alice work on this week and how much did it cost?” will use both get_activity_timeline and get_token_usage.
