Reference
MCP tool reference
The complete public ContextStream tool map, including lifecycle, scope, availability, pagination, and the boundaries between similar records.
This page is the wire-level map for people building an agent, debugging a connection, or checking exactly where a kind of work belongs. The task guides elsewhere use plain language on purpose.
The current complete surface has 20 consolidated domains. A connection may
show fewer when its configured toolset is smaller, an account feature is
unavailable, or disconnected integrations are hidden. Ask help for the live
catalog and use the MCP tools/list response as the authority for the exact
JSON schema your client received.
Required lifecycle
For a coding session, use this order:
- Call
init(folder_path="…")once. Keep the returned workspace, project, and session scope. - Call
context(user_message="…", session_id="…")before acting on each user turn. Ifinstructis exposed, get pending entries first and acknowledge the ones you applied. - Search the ContextStream code index before broad local discovery.
- Use the domain that owns the record. Plans, lessons, documents, tickets, and capsules are not interchangeable generic notes.
- After local file changes, request a project index refresh. A hosted gateway
may report
requires_local_ingest; that is a handoff to the installed machine-local sync path, not an error to retry in a loop.
context can return grounding, lessons, preferences, decisions, matched
skills, routing notices, and version notices. These are operational
instructions for the current turn, not decorative metadata.
Complete domain catalog
| Domain | Owns | Reader guide |
|---|---|---|
init | Session initialization, folder resolution, current workspace/project scope, and index state | Connect your assistant |
context | Turn-specific grounding: relevant history, rules, lessons, preferences, decisions, skills, and routing | What to say |
search | Indexed source and file search, including exact, semantic, pattern, refactor, exhaustive, team, guided, and crawl modes | Search |
instruct | Session-scoped dynamic instructions and their acknowledgement state | Instruction files |
session | Recall, snapshots, decisions, lessons, plans, context restoration, account mode, and session summaries | Past sessions |
memory | Nodes, events, tasks, todos, documents, diagrams, transcripts, decisions, timelines, and team views | What gets remembered |
graph | Dependencies, circular imports, unused code, complexity, quality history/trends/freshness, and saved quality snapshots | Code health |
project | Project records, file listings, index/ingest state, de-indexing, local mappings, statistics, and recent changes | Workspaces and projects |
workspace | Workspace listing, lookup, creation, and workspace-level scope | Workspaces and projects |
reminder | Reminder listing, active reminders, creation, snoozing, completion, and dismissal | Reminders |
integration | Unified Slack, GitHub, Notion, Linear, Jira, and Figma search/knowledge operations | Integrations |
media | Images, video, audio, and documents: indexing, search, status, metadata, and clip extraction | Media and PDFs |
skill | Reusable instruction/action bundles: create, update, run, import, export, share, supersede, and delete | Reusable skills |
capsule | Portable context bundles: create, share, open, hydrate by chunk, inspect, diff, audit, schedule, and revoke | Capsules |
qa | Grounded questions plus curation of the workspace knowledge base | Questions and answers |
entity | Structured workflow records: tickets, handoffs, backlog views, incidents, releases, experiments, goals, key results, sprints, reviews, risks, and discussions | Operational tracking |
vcs | GitHub, GitLab, and Bitbucket repositories, pull requests, issues, commits, trees, search, notifications, links, automations, webhooks, and ingest | Repository workflows |
Hosted and runtime domains
These last domains report on the running product or handle jobs that are available only through the hosted layer.
| Domain | Owns | Reader guide |
|---|---|---|
chart | Workspace dashboard chart queries; hosted/remote deployments only | Analytics and exports |
async_job | Long-running memory exports and aggregates with submit, poll, and paged results; hosted/remote deployments only | Analytics and exports |
help | Live tools, auth, billing, version, workflow, rule previews, bundles, and team subscription status | Troubleshooting |
The catalog names are stable public domains. Individual actions and fields can
grow. Generate clients from tools/list; do not freeze a copied schema from a
documentation page.
Session and instruction actions
init, context, and search are request-shaped domains rather than
action routers. Their behavior is selected by fields such as folder_path,
context mode, and search mode.
The action-routed session surfaces are:
| Domain | Group | Public actions |
|---|---|---|
instruct | Instruction lifecycle | bootstrap, get, push, ack, clear, stats, checkpoint, verify |
session | Capture and lessons | capture, retro_capture, capture_lesson, get_lessons, update_lesson, delete_lesson |
session | Recall and context | recall, ground, set_account_mode, remember, user_context, summary, compress, delta, smart_search, decision_trace, restore_context |
session | Plans | capture_plan, get_plan, update_plan, list_plans |
session | Suggested rules | list_suggested_rules, suggested_rule_action, suggested_rules_stats |
Use retro_capture when saving a decision, note, or snapshot after the fact
from transcript evidence. smart_search searches memory and conversation
history; it is not a substitute for source-code search.
Memory and reusable-context actions
| Domain | Group | Public actions |
|---|---|---|
memory | Nodes and queries | search, create_node, get_node, update_node, delete_node, list_nodes, supersede_node, decisions, timeline, summary |
memory | Events | create_event, get_event, update_event, delete_event, distill_event, list_events, import_batch |
memory | Tasks | create_task, get_task, update_task, delete_task, list_tasks, reorder_tasks |
memory | Todos | create_todo, list_todos, get_todo, update_todo, delete_todo, complete_todo |
memory | Diagrams | create_diagram, list_diagrams, get_diagram, update_diagram, delete_diagram |
memory | Documents | create_doc, list_docs, get_doc, update_doc, delete_doc, create_roadmap |
memory | Transcripts | list_transcripts, get_transcript, search_transcripts, search_archive, delete_transcript |
memory | Team views | team_tasks, team_todos, team_diagrams, team_docs, team_discussions, team_transcript_topics |
reminder | Reminders | list, active, create, snooze, complete, dismiss |
skill | Skills | list, get, create, update, supersede, run, delete, import, export, share |
qa | Questions and knowledge base | ask, search, save_kb, list_kb, get_kb, update_kb, delete_kb, feedback, explain |
Capsules have their own larger lifecycle:
| Domain | Group | Public actions |
|---|---|---|
capsule | Core | open, get, delete, list, create, share |
capsule | Hydration and handoff | chunk, stream, context_doc, bootstrap_prompt, graph, audit, list_shares, revoke_share, ack, primer, diff |
capsule | Scheduled refresh | schedule, schedule_list, schedule_delete |
capsule | Explanation | explain |
Scope and analysis actions
| Domain | Group | Public actions |
|---|---|---|
workspace | Workspace records | list, get, create, delete, associate, bootstrap, team_members, index_settings |
project | Project and index lifecycle | list, get, create, update, merge, combine, index, delete, purge, forget_local, remove_paths, overview, statistics, files, index_status, index_history, ingest_local, team_projects, recent_changes |
graph | Relationships and health | related, dependencies, impact, ingest, outbox_status, outbox_canary, call_path, path, circular_dependencies, unused_code, complexity_metrics, quality_trends, quality_history, quality_freshness, quality_snapshot, contradictions, code_drift, decisions, usages |
entity | Structured records | list, get, create, update, delete |
workspace.delete, project deletion/de-indexing, graph ingestion/outbox
operations, and entity writes are not read-only merely because they share a
consolidated domain with reads. Use the live annotations and obtain user
authorization appropriate to the operation.
External and hosted utility actions
The full integration and vcs action lists and provider-specific contracts
are on the integration action reference
and repository action reference.
| Domain | Group | Public actions |
|---|---|---|
media | Assets | index, status, search, get_clip, list, delete |
chart | Hosted analytics | render, list |
async_job | Hosted long-running jobs | submit_export, submit_aggregate, poll, result |
help | Runtime information | tools, auth, billing, version, workflow, editor_rules, enable_bundle, team_status |
chart.render uses an allowlisted chart identifier. Async submissions require
a collection (transcripts, decisions, lessons, or docs), return a
job_id, and must be polled before paging results.
Search and graph
Use search for source code, symbols, paths, and file content. Its modes are:
| Mode | Use it for |
|---|---|
auto | Normal default; chooses a suitable strategy |
hybrid | Keyword plus semantic retrieval |
semantic | Conceptual questions |
keyword | Exact text or quoted symbols |
pattern | Globs and regular expressions |
exhaustive | Every occurrence in the selected scope |
refactor | Symbol usage and rename-safe navigation |
team | Cross-project team search |
crawl | A deeper multi-modal investigation |
guided | Raw evidence plus bounded navigation for an implementation intent |
Use output_format="paths" for a file set, count for totals, minimal for
compact evidence, and full when snippets and metadata matter. limit and
offset page ordinary results; refactor searches can return an opaque cursor,
which must be passed back unchanged.
Use graph after search when the question is relational: dependency blast
radius, cycles, unused elements, complexity, or quality trends. Graph results
may be cached scans. Check quality freshness before treating a dashboard count
as a current source fact.
Memory, sessions, and structured work
These boundaries prevent the most common data-model mistakes:
| Need | Correct home |
|---|---|
| A durable multi-step implementation plan | session plan actions; capture structured steps and linked tasks |
| A mistake that should warn future work | session lesson actions with trigger, impact, prevention, and severity |
| A decision or session checkpoint | session capture with the matching event type |
| A runbook, ADR, RFC, postmortem, PRD, glossary, or other versioned document | memory document actions |
| A lightweight task tied to a plan | memory task actions with plan and step IDs |
| A personal reminder | reminder |
| A bug, incident, release, sprint, review, risk, or other lifecycle record | entity |
| A portable or shareable context bundle | capsule |
| A handoff workflow record plus a portable payload | An entity handoff paired with a capsule |
The 12 entity kinds are ticket, handoff, backlog_view, incident,
release, experiment, goal, key_result, sprint, review, risk, and
discussion. A ticket can represent a bug, feature, task, chore, or epic;
use the dedicated incident entity when severity and an incident status
timeline matter.
Transcript reads live under memory; ranked continuation and snapshots live
under session. Capture is client/configuration dependent. The presence of a
transcript search action does not mean every client conversation was saved.
Supported content and record values
These are the current exact wire values for the record families that the task-oriented guides describe in plain language.
| Family | Supported values |
|---|---|
node | fact, decision, preference, constraint, habit, lesson, goal, risk, term |
event | decision, preference, insight, uncategorized, note, general, manual_note, implementation, operation, command_execution, file_operation, task, bug, feature, correction, lesson, warning, frustration, conversation, session_snapshot, standup, status_update, question, approval, feedback, discovery, achievement |
document | roadmap, spec, runbook, adr, rfc, postmortem, retro, release_notes, playbook, prd, user_story, persona, interview, design_spec, critique, glossary, oncall_schedule, slo, q_and_a, changelog, style_guide, general |
diagram | flowchart, sequence, class, er, gantt, mindmap, pie, other |
entity_kind | ticket, handoff, backlog_view, incident, release, experiment, goal, key_result, sprint, review, risk, discussion |
media_type | video, audio, image, document |
media_output | remotion, ffmpeg, raw |
qa_knowledge_kind | guidance, guardrail, faq, runbook, caveat |
reminder_status | pending, completed, dismissed, snoozed |
reminder_priority | low, normal, high, urgent |
reminder_recurrence | daily, weekly, monthly |
Capsule inputs have their own policy vocabulary:
| Family | Supported values |
|---|---|
capsule_scope | workspace, project, session |
capsule_mode | live, snapshot |
capsule_audience | self, team, external_agent, public_link, support, bootstrap_link |
capsule_purpose | bootstrap, handoff, snapshot, debug, review, onboarding, external_agent, custom |
capsule_code | none, lazy, inline |
capsule_redaction | none, standard, strict |
capsule_graph | explorer, knowledge, code |
capsule_format | summary, markdown, text, ndjson |
The live schema remains authoritative. In particular, entity body and
query objects are forwarded to the corresponding API resource and can grow
independently from this value table.
Scope and account mode
Reuse the workspace_id and project_id returned by init or context.
Pass them explicitly for writes and for reads where ambiguity would be
dangerous. folder_path resolves a local checkout; target_project is for a
known child project after initialization from a multi-project parent.
Team and personal records can coexist. account_mode chooses team,
personal, or auto; it does not bypass membership or record-level access.
If a response contains a project-routing warning, resolve it before a
project-scoped write.
List APIs do not share one pagination vocabulary. Depending on the domain,
the live schema may use limit/offset, page/page_size, or an opaque
cursor. Preserve cursors exactly and keep all original filters on the next
request.
External systems and availability
Use integration to search and summarize connected product data through one
provider-aware surface. Use vcs for repository-native operations such as
pull diffs, checks, reviews, issue writes, branches, blobs, notifications, and
webhooks. The integration action reference
lists every supported provider/action combination.
chart and async_job require the hosted/remote product layer. Integration
actions require the corresponding account connection. Some managed clients
hide disconnected domains to keep their tool list small; absence can therefore
mean configuration or entitlement, not an old server.
Results, notices, and failures
Tool results can contain both readable text and structured content. Preserve the structured payload when another program consumes the result, but show the human text when explaining it to a person.
Treat these cases distinctly:
- A transport or schema error means the call did not run as requested.
- An in-band routing, archive, stale-index, or
requires_local_ingestnotice is a successful response with a required next step. - A partial result with
has_more, a next offset, or a cursor is not an empty result. - A stale index can still answer about existing indexed code. Refresh before concluding that a newly edited symbol is absent.
- A missing hosted-only or integration action is an availability issue, not a reason to invent a similarly named call.
For the exact server build and currently exposed catalog, call
help(action="version") and help(action="tools", format="full").