Workspace MCP Server
Ask a named Charm a single contextual question inside a Workspace document and get its reply.
|
|
agentName or agentId), and an optional message — and returns the Charm's reply. The Charm answers using everything in the document above the insertion point as its context.https://api.charmiq.ai/mcp/workspaceFor Developers — Workspace is routable but currently not advertised by the root discovery endpoint ( list_servers). Call its URL directly; don't expect it to appear in dynamic discovery yet.
The One Tool
prompt |
prompt(uri, agentName | agentId, as?, message?, referenceMaterial?).uri | charmiq://workspace/{id}[#fragment] or `https://(team |
agentName | agentName or agentId |
agentId | agentName or agentId |
as | |
message | |
referenceMaterial |
charmiq:// form.Where the Question Lands
#fragment portion of the URL — if present — determines where the question is inserted:#fragment | |
#fragment resolving to a known anchor | |
#fragment that does not resolve | anchorResolved: false |
The Charm Sees the Document, Not Your Prompt
prompt is independent — the Charm re-reads the document every time. Prior questions and replies that landed in the document are visible naturally, because they're in the document above where you're inserting now.Per-Run Reference Material
add_context / update_context / remove_context).prompt's referenceMaterial argument adds material for a single call. Each entry is a charmiq:// URI plus optional routing:referenceMaterial: [ { uri: "charmiq://workspace/dennis-memory" }, // the model reads it (default) { uri: "charmiq://file/sales-2025.csv", sendToSandbox: true } // the Charm's code runs against it ]
readByModel: false to hide it from the model, or sendToSandbox: true to give its raw bytes to the code-execution sandbox. Use it whenever material is specific to one run; use the persistent context for material that should stay loaded across runs.referenceMaterial and keep the saved context for the shared, always-on set.Reference Material attached to a Charm does not travel. A Charm is itself a document, and a User can attach Reference Material to it — but that's authoring context for editing the Charm, symmetric to attaching context to a Workspace. It is not carried along when the Charm runs here; a run resolves Reference Material from the document it runs in plus whatever referenceMaterialyou pass.
A Typical Sequence
User shares a Workspace URL with your application. You call prompt(url, "Editor", "User", "What's the main argument?")— answer comes back, and a Q+A block lands at the end of the document.User reads the reply, asks a follow-up. You call prompt(url, "Editor", "User", "And what does it miss?")— the Charm re-reads the document (including the previous Q+A) and answers the follow-up.
Orchestrating a Panel of Charms
prompt looks like Q&A, but its real power is directing several independent Charms against one shared document. The document is the shared reality; each call drops one Charm into it with exactly the context you hand that Charm, and you control the order. Saved context is the always-on set every Charm shares; referenceMaterial is the per-call spotlight — this Charm's memory for this turn.Worked example: a persona panel
One Charm per segment — not "a skeptical buyer" but "Dana, a budget-conscious ops manager burned by two SaaS migrations who reads every renewal clause." Specific personas produce specific reactions. (Agent server: create_agent.)One Workspace per persona, holding their situation — budget, prior tools, current pain. That's their memory, kept separate from their personality (which lives in the Charm's System Prompt). A review document with the draft copy at the top and a ## Reactionsheading. Attach the shared, neutral material — the brief, the product facts — as saved context once.
# sharedBrief is already saved context on reviewDoc — shared by every persona for persona in [Dana, EnterpriseBuyer, StartupFounder]: prompt( uri = reviewDoc, agentName = persona.name, # or agentId = persona.agentId referenceMaterial = [ { uri: persona.memoryDoc } ], # this persona's memory, this call only # no message — the copy and the reactions already in the document ARE the prompt )
Keep each persona in its lane
You are a respondent, not a scriptwriter. Answer ONLY as yourself; never write another persona's words or thoughts. Stop when your point is made. You ARE this persona, not a narrator describing them. Speak in the first person.
Don't summarize the document back to the Charm. Re-stating "the last persona said X, now react to X" in every messagepays tokens to tell a Charm what it can already read above its insertion point. Call the persona, pass its memory, and let it read the room.
Where each piece of material goes
referenceMaterial. If you catch yourself passing the same URI on every call, promote it to saved context and stop repeating it.Patterns
Provide exactly one of agentNameoragentId. No default Charm. If the user's instructions don't specify which Charm to run, ask them.Anchors are best-effort. Check anchorResolvedin the response — fall back gracefully if the document was edited and the anchor no longer exists.Prefer mid-document insertion when the user gave you a fragment. That's almost always what they meant. Appending to the end is the fallback, not the default. Each call is fresh. Don't try to keep a "conversation token." The document is the durable history. Per-call material goes in referenceMaterial. Merged onto the saved context, not persisted. Useadd_contextonly for material that stays loaded across runs.Personas are Charms; situations are Workspaces. Durable personality → System Prompt. Swappable facts → referenceMaterial. One persona re-points at ten scenarios.Direct by sequencing, not narrating. You decide who speaks next and what they can see; let the document carry what was said. The pattern isn't just marketing. Code-review personas, stakeholder sign-off, red-team/blue-team debates, user-research synthesis — anywhere "how would these specific people react to this?" is the question.
Next Steps
prompt.