Context MCP Server
Manage the Reference Material attached to any document — add, remove, enable/disable and route dependents so your Charms see exactly what they need.
|
|
https://api.charmiq.ai/mcp/contextTools
list_context | |
add_context | |
update_context | |
remove_context |
charmiq:// URIs. Get them from the VFS server (list_dir, semantic_search, describe_file).What a Dependent Is
charmiq:// URI attached to a document's context:charmiq://workspace/…, charmiq://charm/…, charmiq://chat/… | ||
charmiq://folder/… | ||
charmiq://file/… |
add_context derives it from the URI scope. Pass the URI; the server resolves the rest.Enabled, readByModel, sendToSandbox
enabled— whether the Charm uses the dependent at all. Newly added dependents are enabled by default. Disable a dependent to keep it attached but temporarily out of the Charm's context.readByModel— whether the model reads a rendered view of the dependent (only when its Model can render the type). The "the model reads it" path. Default on.sendToSandbox— whether the dependent's raw bytes go to the Charm's code-execution sandbox. The "the code runs against it" path (e.g. a CSV the Charm's code parses). Default off.
readByModel and sendToSandbox are independent — a dependent can feed the model, the sandbox, both, or neither. update_context sets them per-dependent.Membership Rules
Dependents are references, not copies. Adding a document to a context does not move or duplicate it. Context is per-User. Each User has their own context for a given document; you only ever see and modify the calling User's context. Context belongs to the document it's attached to. A run resolves Reference Material from the document it runs in — never from the Charm that runs. Removing a dependent leaves the underlying content untouched. remove_contextdetaches; it never deletes the document, asset or folder.Deleted dependents are skipped. If a dependent's underlying document was deleted, list_contextsilently omits it.
A Charm's own context is authoring context — it does not travel. A Charm is itself a document, so you can attach context to charmiq://charm/…— but that's the Reference Material for editing that Charm, symmetric to attaching context to a Workspace. When the Charm runs on a Workspace, only the Workspace's context applies. For per-run material, use the Workspace server'sreferenceMaterialargument instead.
Bulk vs. Single Operations
update_context— passdependentUrito update one dependent (any ofenabled,readByModel,sendToSandbox). OmitdependentUrito applyenabledto every dependent at once.readByModel/sendToSandboxcan only be set on a single dependent; trying to set them in bulk is an error.remove_context— passdependentUristo remove specific dependents. Omit it to clear the entire context.
VFS Integration
charmiq:// URIs, not content. To discover, read or create the documents you attach, use the VFS server:list_dir/semantic_search/grep_searchto find URIs to adddescribe_fileto confirm what a URI points at before attaching itcreate_fileto create a document, thenadd_contextto attach it
list_context are live VFS URIs — hand them straight back to VFS tools to read or edit the dependent content.Patterns
Read before you write. Call list_contextto see the current dependents rather than caching them — the User can change context in the UI between your calls.Add by URI, never by type. Let add_contextderive the dependent type from the URI scope. Don't try to classify documents yourself.Disable instead of remove when iterating. If you're tuning what a Charm sees, toggle enabledwithupdate_contextrather than removing and re-adding — it preserves the dependent's routing settings.Match routing to use. Turn on sendToSandboxonly for dependents the Charm's code actually parses; the defaultreadByModelcovers the "model reads it" case.Persist what stays; pass what's per-run. Use add_contextfor material that stays loaded across runs. For a single run, prefer the Workspace server'sreferenceMaterialargument — merged onto the saved context for that one call, never persisted.
A Minimum Viable Call
# add_context — attach a dependent curl -X POST https://api.charmiq.ai/mcp/context \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "add_context", "arguments": { "uri": "charmiq://workspace/abc123", "dependentUris": ["charmiq://workspace/def456"] } } }'
list_context with { "uri": "charmiq://workspace/abc123" } — the response structuredContent.dependents array lists each attached dependent as a charmiq:// URI with its enabled, readByModel and sendToSandbox flags.