Docs · Browse sections

MCP Tools

ContextStream MCP Tools (v0.4.x)

v0.4.x uses ~11 consolidated domain tools with action/mode dispatch (~75% token reduction).

Note:You don't need to call these tools directly. Just ask your AI naturally (e.g., "what did we decide about auth?") and it will use the right tools automatically. See the Quickstart for setup.
v0.4.x Architecture: Tools use action/mode dispatch:
  • session(action="capture", event_type="decision", ...)
  • search(mode="semantic", query="auth", limit=3)
  • graph(action="dependencies", target=...)
  • integration(provider="github", action="search", query=...)

Use CONTEXTSTREAM_PROGRESSIVE_MODE=true for ~2 router meta-tools (most compact).

GitHub + Slack Integrations: When connected, integration data automatically enriches context_smart—your AI surfaces relevant GitHub issues, PRs, and Slack discussions without extra calls. See Integrations docs for setup.
Check your MCP server version:contextstream-mcp --version

session_init

Initialize a session and load workspace/project context. Call once at conversation start.

Dispatch: params

session_init(...)

Initialize session with folder_path and context_hint. Returns workspace info, recent memory, decisions, and lessons.

Common uses

  • "Initialize ContextStream for this repo and load relevant context."
  • "If workspace isn't resolved, re-run with allow_no_workspace: true."

context_smart

Get relevant context for the current user message. Call before every response after session_init.

Dispatch: params

context_smart(...)

Analyzes user_message and returns semantically relevant context in minified format (~200 tokens).

Common uses

  • "Get relevant context for my current question before you answer."

session

Session management: capture decisions, recall context, manage lessons, compress chat.

Dispatch: action

session(action="capture", ...)

Capture important context (decision, preference, task, bug, feature, insight).

Common uses

  • "Capture decision: We will use PostgreSQL for persistence."
session(action="recall", ...)

Recall relevant decisions and memory using natural language.

Common uses

  • "What did we decide about authentication?"
session(action="remember", ...)

Save something to memory using natural language. Use await_indexing: true for immediate searchability.

Common uses

  • "Remember that I prefer TypeScript strict mode."
session(action="capture_lesson", ...)

Capture a lesson learned from a mistake, correction, or frustration.

Common uses

  • "Capture lesson: Always run tests before pushing to production."
session(action="get_lessons", ...)

Retrieve lessons filtered by category, severity, or semantic query.

Common uses

  • "Show me lessons about deployments."
session(action="summary", ...)

Get a compact summary of workspace/project context.

Common uses

  • "Give me a summary of this workspace."
session(action="compress", ...)

Extract and store key info from chat history as memory events.

Common uses

  • "Compress this chat history into decisions, preferences, and tasks."
session(action="delta", ...)

Get new context added since a given timestamp.

Common uses

  • "What changed since yesterday?"
session(action="smart_search", ...)

Search memory and code with automatic context enrichment.

Common uses

  • "Find everything related to payment processing."
session(action="user_context", ...)

Retrieve user preferences and coding style from memory.

Common uses

  • "What are my preferences and coding style?"
session(action="decision_trace", ...)

Trace the provenance and history of a decision.

Common uses

  • "Where did the JWT decision come from?"

search

Search your indexed codebase by meaning, keywords, or patterns.

Dispatch: mode

search(mode="semantic", ...)

Semantic vector search - find code by meaning.

Common uses

  • "Find code related to authentication."
search(mode="hybrid", ...)

Hybrid search combining semantic and keyword matching.

Common uses

  • "Search for rate limiting implementation."
search(mode="keyword", ...)

Exact keyword search.

Common uses

  • "Find occurrences of 'jwt'."
search(mode="pattern", ...)

Pattern/regex search.

Common uses

  • "Find TODO|FIXME notes."

memory

Create, search, and manage memory events and knowledge nodes.

Dispatch: action

memory(action="create_event", ...)

Create a memory event for a workspace/project.

Common uses

  • "Create a decision memory about our caching strategy."
memory(action="list_events", ...)

List memory events for a workspace (optionally scoped to a project).

Common uses

  • "List recent memory events."
memory(action="get_event", ...)

Get a specific memory event by ID.

Common uses

  • "Get details of event abc123."
memory(action="update_event", ...)

Update a memory event.

Common uses

  • "Update the title of this event."
memory(action="delete_event", ...)

Delete a memory event.

Common uses

  • "Delete event abc123."
memory(action="distill_event", ...)

Extract and condense key insights from a memory event.

Common uses

  • "Distill key insights from this event."
memory(action="search", ...)

Search memory events/notes.

Common uses

  • "Search memory for 'JWT' decisions."
memory(action="decisions", ...)

List decision summaries from workspace memory.

Common uses

  • "List our key architectural decisions."
memory(action="timeline", ...)

Get chronological timeline of memory events.

Common uses

  • "Show the timeline of recent work in this workspace."
memory(action="summary", ...)

Get a condensed summary of workspace memory.

Common uses

  • "Summarize what we've done recently."
memory(action="create_node", ...)

Create a knowledge node with optional relations.

Common uses

  • "Create a knowledge node for the auth architecture."
memory(action="list_nodes", ...)

List knowledge graph nodes.

Common uses

  • "List all knowledge nodes."
memory(action="get_node", ...)

Get a specific knowledge node by ID.

Common uses

  • "Get node details."
memory(action="update_node", ...)

Update a knowledge node.

Common uses

  • "Update this knowledge node."
memory(action="delete_node", ...)

Delete a knowledge node.

Common uses

  • "Delete this node."
memory(action="supersede_node", ...)

Replace a knowledge node with updated information (maintains history).

Common uses

  • "Supersede this decision with new information."

rules

Import and reconcile AI coding rules files across tools, repos, and workspaces.

Dispatch: tool

import_rules_file(...)

Normalize local files, GitHub repos, or another workspace's rules into canonical knowledge nodes.

Common uses

  • "Import AGENTS.md into the Engineering workspace."
  • "Scan a GitHub repo for CLAUDE.md, Cursor, Windsurf, and Copilot rules."
diff_rules(...)

Compare two rules sources and return contradictions, duplicates, overlaps, gaps, and a unified diff.

Common uses

  • "Diff Engineering and Marketing workspace rules."
  • "Compare a local CLAUDE.md against .cursor/rules in the repo."
bulk_import_rules(...)

Import multiple rule sources into one workspace in a single request.

Common uses

  • "Bulk import CLAUDE.md, AGENTS.md, and .cursor/rules into one workspace."
bulk_diff_rules(...)

Run pairwise reconciliation diffs across several rule sources at once.

Common uses

  • "Compare Engineering, Marketing, and Support rule sets side by side."

graph

Code analysis: dependencies, impact, call paths, circular dependencies, unused code.

Dispatch: action

graph(action="dependencies", ...)

Query dependency graph for a module/function.

Common uses

  • "What depends on UserService?"
graph(action="impact", ...)

Analyze impact of changing a target node.

Common uses

  • "What would be affected if I change the User model?"
graph(action="ingest", ...)

Build and persist the code graph.

Common uses

  • "Ingest the graph for this project."
graph(action="call_path", ...)

Find call path between two targets.

Common uses

  • "Trace the call path from login() to the database."
graph(action="circular_dependencies", ...)

Detect circular dependencies in project code.

Common uses

  • "Are there any circular dependencies?"
graph(action="unused_code", ...)

Detect unused code in project.

Common uses

  • "Find unused code in this project."
graph(action="related", ...)

Find related nodes in the knowledge graph.

Common uses

  • "What knowledge is related to our JWT decision?"
graph(action="path", ...)

Find a path between two knowledge nodes.

Common uses

  • "How is auth connected to payments?"
graph(action="decisions", ...)

Decision history in the knowledge graph.

Common uses

  • "Show decision history for this area."
graph(action="contradictions", ...)

Find contradicting information related to a knowledge node.

Common uses

  • "Are there any contradicting decisions?"

project

Create, manage, and index projects; list files and check indexing status.

Dispatch: action

project(action="list", ...)

List projects (optionally by workspace).

Common uses

  • "Show me all projects."
project(action="get", ...)

Get project details by ID.

Common uses

  • "Get details for this project."
project(action="create", ...)

Create a project within a workspace.

Common uses

  • "Create a new project called api-service."
project(action="update", ...)

Update a project (rename or change description).

Common uses

  • "Rename this project."
project(action="index", ...)

Trigger indexing for a project.

Common uses

  • "Index this project for search."
project(action="overview", ...)

Get project overview with summary information.

Common uses

  • "Give me an overview of this project."
project(action="statistics", ...)

Get project statistics (files, lines, complexity).

Common uses

  • "Show project statistics."
project(action="files", ...)

List all indexed files in a project.

Common uses

  • "What files are indexed in this project?"
project(action="index_status", ...)

Get project indexing status.

Common uses

  • "Is indexing complete?"
project(action="ingest_local", ...)

Ingest local files into ContextStream for indexing/search.

Common uses

  • "Index this repository for search and analysis."

workspace

Create and manage workspaces; associate folders and bootstrap new workspaces.

Dispatch: action

workspace(action="list", ...)

List accessible workspaces.

Common uses

  • "Show me all my workspaces."
workspace(action="get", ...)

Get workspace details by ID.

Common uses

  • "Get details for this workspace."
workspace(action="bootstrap", ...)

Create a new workspace and onboard the current folder as a project.

Common uses

  • "Create a workspace called Acme and onboard this repo as a project."
workspace(action="associate", ...)

Associate a folder/repo with a workspace after user selection.

Common uses

  • "Associate this folder with the correct workspace."

reminder

Create and manage reminders for follow-up tasks.

Dispatch: action

reminder(action="list", ...)

List all reminders.

Common uses

  • "Show my reminders."
reminder(action="active", ...)

Get pending and overdue reminders.

Common uses

  • "What reminders are due?"
reminder(action="create", ...)

Create a new reminder.

Common uses

  • "Remind me to review the PR tomorrow."
reminder(action="snooze", ...)

Snooze a reminder.

Common uses

  • "Snooze this reminder for 1 hour."
reminder(action="complete", ...)

Mark a reminder as complete.

Common uses

  • "Mark this reminder done."
reminder(action="dismiss", ...)

Dismiss a reminder.

Common uses

  • "Dismiss this reminder."

integration

Access GitHub and Slack data synced to your workspace.

Dispatch: action

integration(action="status", ...)

Check health and sync status of connected integrations.

Common uses

  • "Are my GitHub and Slack integrations connected?"
integration(action="search", ...)

Search across GitHub and/or Slack. Use provider='github', 'slack', or 'all'.

Common uses

  • "Search GitHub for 'authentication'."
  • "Search Slack for 'deployment'."
  • "Search all integrations for 'release'."
integration(action="stats", ...)

Get overview stats for an integration. Use provider='github' or 'slack'.

Common uses

  • "Show me GitHub activity stats."
  • "What's our Slack sync status?"
integration(action="activity", ...)

Get recent activity feed. Use provider='github' or 'slack'.

Common uses

  • "Show recent GitHub activity."
  • "What's been happening in Slack?"
integration(action="contributors", ...)

Get top contributors. Use provider='github' or 'slack'.

Common uses

  • "Who are the top GitHub contributors?"
integration(action="knowledge", ...)

Get decisions, lessons, and insights extracted from integrations.

Common uses

  • "What decisions were made in GitHub issues?"
  • "Show lessons learned from Slack discussions."
integration(action="summary", ...)

Get a high-level summary of integration activity.

Common uses

  • "Summarize GitHub activity for this week."
  • "Give me a Slack summary for the last 7 days."
  • "Weekly standup summary from GitHub and Slack."
integration(action="channels", ...)

List synced Slack channels. (provider='slack' only)

Common uses

  • "Which Slack channels are we tracking?"
integration(action="discussions", ...)

Get high-engagement Slack threads. (provider='slack' only)

Common uses

  • "What are the key discussions from Slack this week?"
integration(action="repos", ...)

List synced GitHub repositories. (provider='github' only)

Common uses

  • "Which repos are we tracking?"
integration(action="issues", ...)

Get GitHub issues and PRs. (provider='github' only)

Common uses

  • "Show open issues from GitHub."

entity

Unified CRUD across taxonomy expansion entities. Kinds: ticket, handoff, backlog_view, incident, release, experiment, goal, key_result, sprint, review, risk. Body is free-form JSON forwarded to the API; defaults workspace_id/project_id to active scope.

Dispatch: action

entity(action="list", ...)

List entities of a given kind with optional filters. Pass kind="ticket"|"handoff"|"incident"|... and a query={...} object whose keys become URL query params.

Common uses

  • "List open bugs."
  • "Show severe risks that are still open."
  • "What incidents are still investigating?"
  • "List goals for 2026-Q2."
  • "Show the active sprint."
entity(action="get", ...)

Fetch one entity by id. Pass kind="<kind>" and id="<uuid>".

Common uses

  • "Show me ticket <uuid>."
  • "Fetch incident <uuid>."
  • "Get the goal record."
entity(action="create", ...)

Create an entity. Pass kind + body={...}. Special case: kind="key_result" requires goal_id in body and posts to the parent goal.

Common uses

  • "Create a bug ticket: 'Replication lag spiking, sev2 risk'."
  • "Open a sev2 incident on the API service."
  • "Track this 1.4.0 release; deployed to prod."
  • "Create an OKR for Q2: ship 100 customers."
  • "Add a key result to goal <uuid>: MAU > 10k."
  • "Schedule sprint 42, two weeks starting Monday."
  • "Request a security review for github:org/repo#123."
  • "Log a major-impact risk: third-party billing rate limits."
  • "Create a now/next/later backlog view."
  • "Open a handoff to claude with summary + open questions."
entity(action="update", ...)

Patch an entity. Pass kind + id + body={...} with the fields to change. Status transitions auto-set timestamps (resolved_at, closed_at, deployed_at, etc.).

Common uses

  • "Mark ticket <uuid> as resolved."
  • "Move incident <uuid> to mitigated."
  • "Mark release 1.4.0 as deployed."
  • "Update the sprint goal."
  • "Approve PR review <uuid>."
entity(action="delete", ...)

Soft-delete an entity by id. Pass kind + id. Sets deleted_at — rows aren't physically removed.

Common uses

  • "Delete the duplicate ticket."
  • "Cancel sprint <uuid>."

capsule

Portable, scoped, expiring snapshots of project context — share with a teammate, hand off to a fresh agent, or paste into ChatGPT/Claude as a single URL.

Dispatch: action

capsule(action="create", ...)

Mint a new capsule for the current scope (workspace, project, or session).

Common uses

  • "Package up everything we just decided so I can hand it to Sara."
  • "Create a project capsule for handoff."
capsule(action="share", ...)

Mint a shareable URL: team (authenticated, reusable, 7-day default), external_agent (single-use, 1-day, paste into LLMs), public_link, or support.

Common uses

  • "Share that capsule with Sara — she'll open it from the dashboard."
  • "Mint a URL I can paste into ChatGPT for an external review."
capsule(action="open", ...)

Resolve a capsule by id, share token, or pasted URL. Returns the same picture the sender saw.

Common uses

  • "Open the capsule from yesterday's handoff."
  • "Open this share link."
capsule(action="bootstrap_prompt", ...)

Render the capsule as paste-ready Markdown — drops directly into a fresh ChatGPT or Claude session as a handoff prompt. Mirrors the dashboard's Bootstrap prompt copy button.

Common uses

  • "Render this capsule as a paste-ready handoff prompt for a fresh agent."
capsule(action="graph", ...)

Fetch the explorer (file tree), knowledge (decisions/lessons graph), or code (symbol-level dependencies) graph as JSON via a share token.

Common uses

  • "Show me the knowledge graph from the capsule Sara sent."
  • "Pull the code graph from this capsule."
capsule(action="list", ...)

List capsules in scope (workspace or project).

Common uses

  • "Show me my recent capsules."
capsule(action="list_shares", ...)

Active shares for a capsule — single-use unread, multi-use, revoked.

Common uses

  • "List every active share for this capsule."
capsule(action="revoke_share", ...)

Burn a share immediately. Subsequent reads return 410 Gone, regardless of remaining uses or expiry.

Common uses

  • "Revoke the share I sent to the contractor — they're done."

qa

Ask the workspace knowledge base when stuck. Grounded answers from ContextCode citing decisions, lessons, docs, and stored guidance — not a reflex, not a last resort.

Dispatch: action

qa(action="ask", ...)

Submit a question, get a grounded answer with citations and confidence. The only action that calls upstream.

Common uses

  • "What infra should I use for new ContextStream services?"
  • "Why did we pick PostgreSQL over MySQL?"
  • "Is there a runbook for the kind of incident I just hit?"
qa(action="search", ...)

Vector-similarity-free listing of prior Q&A in scope. Useful as 'have we asked this before?' before burning a fresh ask.

Common uses

  • "Have we asked anything about deploy steps?"
qa(action="save_kb", ...)

Store a knowledge-base entry the agent will draw from. Five kinds: guidance (a steer), guardrail (a hard constraint applied every turn), faq, runbook, caveat.

Common uses

  • "Save a guardrail: always require an integration test for new payment flows."
  • "Add an FAQ for our deploy steps."
qa(action="list_kb", ...)

Browse stored knowledge base items in scope.

Common uses

  • "Show me the team's guardrails."
qa(action="feedback", ...)

Rate an answer (-1 negative, 0 clear, +1 positive) so future retrievals weight it appropriately.

Common uses

  • "That answer was great — mark it positive."

skill

Reusable instruction + action workflows that persist across sessions. Skills bundle context, prompt, and tool-use into a callable named action.

Dispatch: action

skill(action="list", ...)

Browse available skills in scope.

Common uses

  • "What skills do I have available?"
skill(action="run", ...)

Execute a skill by name.

Common uses

  • "Run the deploy-safety-checker skill."
skill(action="create", ...)

Define a new skill with an instruction body and optional trigger patterns.

Common uses

  • "Create a skill for code-review checklist."
skill(action="import", ...)

Import skills from a CLAUDE.md, .cursorrules, or other rule file.

Common uses

  • "Import skills from my CLAUDE.md."

instruct

Session-scoped instruction cache. Lets an agent push, fetch, and acknowledge per-session instructions that persist across turns within the same session.

Dispatch: action

instruct(action="get", ...)

Load current instruction entries for this session. Quiet read called automatically before the per-turn context fetch.

Common uses

  • "What's in my instruction cache right now?"
instruct(action="push", ...)

Add new instruction entries to the session cache.

Common uses

  • "Push a session instruction: prefer terse responses."
instruct(action="ack", ...)

Acknowledge instruction entries by id so they aren't re-surfaced.

Common uses

  • "Acknowledge the last 3 instructions."
instruct(action="stats", ...)

Get session cache stats — version, count, last-write.

Common uses

  • "How many entries are in my session cache?"
instruct(action="clear", ...)

Clear all instruction state for the session.

Common uses

  • "Clear my session instruction cache."

media

Index, search, and pull clips from photos, videos, audio, and documents/PDFs the workspace has stored. Returns indexed metadata, transcripts, and previews.

Dispatch: action

media(action="list", ...)

Browse indexed media. Filter by content_types: image / video / audio / document.

Common uses

  • "Show me indexed photos."
  • "List the audio recordings."
media(action="search", ...)

Find media by query — works across photo content, video frames, audio transcripts, and document text.

Common uses

  • "What's in this PDF about onboarding?"
  • "Find the screenshot where the dashboard had the red banner."
media(action="index", ...)

Submit a file path or external URL for indexing. Asynchronous — poll with status.

Common uses

  • "Index this PDF."
  • "Index the screenshots in /home/me/Pictures."
media(action="status", ...)

Check indexing progress for a content_id.

Common uses

  • "Is the doc finished indexing yet?"
media(action="get_clip", ...)

Extract a clip from indexed video or audio by start/end timestamp. Output formats: raw, ffmpeg, remotion.

Common uses

  • "Pull a 30-second clip from 1:34 to 2:04."

help

Utility and help functions.

Dispatch: action

help(action="tools", ...)

List available tools and their actions.

Common uses

  • "What tools are available?"
help(action="auth", ...)

Get current authenticated user info.

Common uses

  • "Who am I authenticated as?"
help(action="version", ...)

Get the running MCP server version.

Common uses

  • "What version of the MCP server is running?"
help(action="editor_rules", ...)

Generate ContextStream AI rule files for editors.

Common uses

  • "Generate ContextStream rules for this project."
help(action="enable_bundle", ...)

Enable a tool bundle in progressive mode.

Common uses

  • "Enable the memory bundle."
Legacy Tool Names (v0.3.x):If you're using an older MCP server version or non-consolidated mode, tools are exposed with granular names like session_capture, search_semantic, graph_dependencies. Upgrade to v0.4.x for ~75% token reduction with consolidated domain tools.