Build on CharmIQ - MCP
The complete developer reference for CharmIQ's MCP surface — what's exposed, how it's authenticated, and which server to reach for.
|
|
You're writing an application for CharmIQ — a Charm, an Application that runs inside CharmIQ, or a backend service that reaches in. The MCP surface is your API; this is the developer reference. You're using your AI coding assistant to write that CharmIQ Application. Same setup as the broad case, plus the Docs server so the assistant knows the CharmIQ API surface before it writes a line of code.
The Surface
/mcp | list_servers — runtime catalog of every available server and tool | |
/mcp/vfs | ||
/mcp/action | ||
/mcp/agent | ||
/mcp/application | ||
/mcp/chat | ||
/mcp/collection | ||
/mcp/company | ||
/mcp/context | ||
/mcp/docs | ||
/mcp/generation | ||
/mcp/git | ||
/mcp/note | ||
/mcp/share | ||
/mcp/usage | ||
/mcp/workspace | ||
/mcp/echo | echo, echo_transform, echo_error) for verifying connectivity |
https://api.charmiq.ai. The base URL https://api.charmiq.ai/mcp exposes a single list_servers tool that returns the same table above, plus the exact list of tools each server provides — the easiest way to discover what's available at runtime instead of pinning it at build time.For Developers — The Workspace server is currently routable but not advertised by the root discovery endpoint. Treat it as a stable URL you call directly rather than something list_serverswill return.
The Authentication Model
Your application fetches authorization server metadata from /.well-known/oauth-authorization-server.It registers itself via /oauth/register(RFC 7591) the first time, then reuses that client.It sends the user through the Authorization Code + PKCE flow. The user picks an Organization and approves the requested scopes. Your application receives a JWT access token scoped to that Organization.
/mcp. Full reference — endpoints, scopes, lifetimes, server-to-server credentials — lives in MCP Authentication.Organizations and Billing
The charmiq:// URI Scheme
charmiq:// URIs. Each server documents the scopes its tools accept.charmiq://{scope}/{id}[?format=...&version=...]
workspace | |
charm | |
chat | |
folder | |
source | |
file |
charmiq:// URI:Web: https://team.charmiq.ai/source/wGPmxb8DN3kgivtbpYSF MCP: charmiq://source/wGPmxb8DN3kgivtbpYSF
noteId; pass it as parentId to add another Note.Context Dependents
richtext | charmiq://workspace/…, charmiq://charm/…, charmiq://chat/… | |
folder | charmiq://folder/… | |
asset | charmiq://file/… |
{ dependentType, dependentId }). Others accept bare identifier strings — extract the {id} portion from the URI. Each tool's description says which.A Minimum Viable Call
# After OAuth, you have an access token. Call list_docs: curl -X POST https://api.charmiq.ai/mcp/docs \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "list_docs", "arguments": {} } }'
structuredContent.docs array with { slug, name, description } for each documentation page. Pick one and call read_doc with that slug to get the full Markdown.Conventions to Know
Structured output. Every tool returns both a human-readable content[](text) array and astructuredContentobject with the typed result. Build againststructuredContent.Pagination. Each tool documents its page size and continuation arguments. Versions and formats. VFS reads accept ?version=Nand?format=markdown|plain|htmlquery parameters on the URI. Defaults depend on document type.Soft vs. hard delete. Documents soft-delete (recoverable through the UI). Assets, Agents, and a few other types hard-delete. The tool description always says which. Role-gated visibility. Some servers expose extra capabilities only when the calling user holds the corresponding role (admin-only scopes in VFS, admin-only metadata fields in Collection). The discovery catalog reflects what the calling user is actually allowed to see.
Patterns
Discover at runtime. Call list_serversonce at startup and reflect its output in your application's capability map. Never hard-code which servers exist.Treat charmiq://URIs as opaque. Don't parse them by hand — the format is stable but the scopes will grow. Pass URIs as strings to tools that support their scope.One token per Organization. If your application operates across Organizations, authorize each one separately and keep tokens isolated. A token cannot reach into another Organization's resources. Use Docsas a smoke test. It's read-only, it costs nothing, and it works on every account. If it works, your OAuth flow works.