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.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.
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.
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.
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.
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.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.
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.
Saga names follow a deterministic pattern based on the event source:
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 optionalrepository 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 usingget_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.