> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cogniscape.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Cogniscape MCP

> Query your development knowledge graph from any MCP-enabled AI assistant.

This is where the magic happens. The MCP Reader is the interface designed for **engineering managers, tech leads, and everyone above them**. It gives you complete freedom to query your knowledge graph and shape the data exactly the way you need it.

Ask anything: team performance summaries, AI token ROI, sprint progress, individual contribution reports. The MCP Reader understands natural language, so you simply describe what you need and get the answer in the format you prefer.

## Authentication

The MCP Reader uses **OAuth with JWT**. On first connection, your client will open a login page where you authenticate with your Cogniscape account. Tokens expire after 60 minutes and are automatically renewed. After 30 days of inactivity, a new login is required. This applies to all clients listed in the [setup guide](/mcp-reader/setup).

## Beyond interactive queries

The MCP Reader is not limited to AI clients like Claude Desktop. It's a standard MCP endpoint that can be integrated into **automated workflows and scheduled tasks**. Build pipelines that generate reports automatically and deliver them via Slack, email, WhatsApp, Telegram, or any channel your organization uses. Weekly team summaries, monthly performance reviews, daily token usage digests: all fully automated.

## Tools

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`, `linear`, or `monday` |
| `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                            |

**When to use:** Broad questions like "what happened this week?", "what did the team deliver?", or any time-based query.

### 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        |

**When to use:** Entity questions like "who is Alice?", "what is the billing service?", or "find all repositories related to payments".

### 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) |

**When to use:** Relationship questions like "what PRs did Alice merge?", "which issues are blocking the release?", or "what was authored this week?" (use `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 |

**When to use:** Provenance questions like "when was this information added?", "show me the raw events from yesterday", or debugging data ingestion.

### 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                      |

<Info>
  When `date_start` and `date_end` are provided, the `period` parameter is ignored.
</Info>

**When to use:** Cost questions like "how much did Claude cost this week?", "what's our token usage by developer?", or "show me AI spending for the billing repo".

### 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                      |

**When to use:** ROI questions like "what's the cost per developer?", "show me the spending trend", or "is our AI investment efficient?".

### 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                                                                                |

Saga names follow a deterministic pattern based on the event source:

| Event type            | Saga name format               |
| --------------------- | ------------------------------ |
| Pull request events   | `PR #<number> <repository>`    |
| Issue events          | `Issue #<number> <repository>` |
| Coding session events | `Session <session_id>`         |

**When to use:** Lifecycle questions like "show me the full history of PR #99", "what happened with issue #42?", or "trace this coding session from start to finish".

## 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.

## Tool selection guide

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` |

<Tip>
  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`.
</Tip>