Every Application — inline or folder-based — has 

 available before your first line of script runs. The platform injects it automatically. You don't import it. You don't initialize it. It's just there.

This page covers the full surface of the bridge.

Collaborative text blocks stored in the document. OT-managed. Safe for concurrent writes.

type AppContentChange = {
  id: string;        // Stable ProseMirror node ID
  name?: string;     // Human-readable name
  content: string;   // Current text
  deleted?: boolean; // True if the block was removed
};

type TextChange = {
  from: number;   // Start offset
  to: number;     // End offset (same as from for pure inserts)
  insert: string; // Text to insert (empty for pure deletes)
};

 for patterns and the selector reference.

A single JSON blob stored in the document. Last-write-wins.

Authenticate with external providers (Google, GitHub, Microsoft, Slack, and 30+ others) using the same OAuth infrastructure that powers Charm integrations.

Your Organization administrator must have an Integration configured for the provider before 

 will work. The integration exists at the Organization level — Applications use it, they don't create it.

// 1. Register (required before getValidAuth)
await window.charmiq.oauth.register({
  appId: 'com.mycompany.analytics',  // Unique reverse-domain identifier
  name: 'Analytics Dashboard',
  description: 'Reads Google Analytics data',
});

// 2. Get a token
const auth = await window.charmiq.oauth.getValidAuth({
  providerUrl: 'https://accounts.google.com',
  scopes: ['https://www.googleapis.com/auth/analytics.readonly'],
});
// auth.accessToken — ready to use

// 3. Use it
const res = await fetch('https://analyticsdata.googleapis.com/...', {
  headers: { Authorization: `Bearer ${auth.accessToken}` },
});

// 4. Revoke when done
await window.charmiq.oauth.revokeAuth(auth);

 Each Application gets its own isolated token scope. Application A's tokens cannot be read or used by Application B, even if both connect to the same provider with the same account.

Connect to MCP servers and call their tools. CharmIQ manages credentials, transport and connection lifecycle on behalf of your iframe.

CharmIQ's built-in MCP servers are pre-connected. Call their tools directly using the server name as the alias — no 

// No connect() needed for Platform servers
const tools = await window.charmiq.mcp.listTools('generation');
const result = await window.charmiq.mcp.callTool('generation', 'create_image', {
  prompt: 'A mountain at sunrise',
});
console.log(result.content[0].text);

Servers your Organization administrator has configured. Discover them via 

 is an alias you choose — a local name you use in subsequent 

For servers not configured at the Organization level:

// OAuth by provider URL
await window.charmiq.mcp.connect('bigquery', {
  url: 'https://bigquery.googleapis.com/mcp',
  transport: 'proxy',  // Routes through CharmIQ cloud function (bypasses CORS)
  auth: {
    type: 'oauth',
    providerUrl: 'https://accounts.google.com',
    scopes: ['https://www.googleapis.com/auth/bigquery'],
  },
});

// No-auth server (direct browser connection)
await window.charmiq.mcp.connect('local', {
  url: 'http://localhost:8080/mcp',
  transport: 'direct',  // Browser connects directly (requires permissive CORS)
  auth: { type: 'none' },
});

type McpToolCallResult = {
  content: Array<{ type: string; text: string }>;
  structuredContent?: unknown;
  isError?: boolean;
};

When connecting via an Organization-defined server, the 

 field in the server descriptor lists the tools your Organization administrator has permitted. 

 returns only what's allowed. You can never call a tool outside the ceiling regardless of what the MCP server advertises.

Application discovery is how Applications find each other and communicate. See 

// Advertise a capability
window.charmiq.advertise('chart', {
  setData: (data) => { chart.update(data); },
  data$: () => dataSubject.asObservable(),
});

// Discover and call
window.charmiq.discover('chart').subscribe(providers => {
  if (providers[0]) providers[0].setData(myData);
});

The bridge uses RxJS Observables for reactive data. 

 is available globally inside every Application — you don't need to import it. Use 

 — Patterns for the two storage channels.

 — How the manifest, virtual file system, and esbuild work together.

The complete charmiq reference — storage, OAuth, MCP, and Application discovery.

Method	Returns	Description
`onChange$(selector?)`	`Observable<AppContentChange>`	Watch for changes. Fires immediately with current state, then on every change from any source.
`get(selector?)`	`Promise<string>`	Get the current text content of a block.
`set(content, selector?, name?)`	`Promise<void>`	Replace full content. Creates a new block if selector doesn't match.
`applyChanges(changes, selector?)`	`Promise<void>`	Apply incremental text edits through OT. Prefer over `set()` for editor-like Applications.
`remove(selector?)`	`Promise<void>`	Delete an app-content block.

Method	Returns	Description
`onChange$()`	`Observable<any>`	Watch for state changes. Fires immediately with current state.
`get()`	`Promise<any>`	Get the current state object.
`set(state)`	`Promise<void>`	Replace the entire state object.

Method	Returns	Description
`register(config)`	`Promise<void>`	Register your application identity. Call once on load before calling `getValidAuth()`.
`getValidAuth(options)`	`Promise<AuthResult>`	Get a valid (non-expired) access token. Opens a consent popup if needed. Refreshes automatically if expired.
`refreshAuth(auth)`	`Promise<AuthResult>`	Explicitly refresh an auth result.
`revokeAuth(auth)`	`Promise<void>`	Revoke access. Pass the AuthResult object.

Option	Description
`providerUrl`	OAuth provider URL. Platform resolves the matching Integration from your Organization config.
`integrationId`	Exact Integration ID. Use when you need to target a specific Integration (dev/testing).
`scopes`	Requested scopes. Falls back to the Integration's configured `defaultScopes` if omitted.
`prompt`	`'auto'` (default) — uses cached token or auto-selects single account. `'select_account'` — always shows the account picker.

Method	Returns	Description
`listServers()`	`Promise<McpServerDescriptor[]>`	List all available MCP servers: CharmIQ servers and Organization-defined servers.
`connect(alias, config)`	`Promise<McpServerInfo>`	Connect to an Organization-defined or explicit server. Platform servers don't need `connect()`.
`disconnect(alias)`	`Promise<void>`	Disconnect a server by its alias.
`listTools(serverAlias)`	`Promise<McpToolDescriptor[]>`	List tools on a connected server.
`callTool(serverAlias, toolName, args?)`	`Promise<McpToolCallResult>`	Call a tool.

Developer | The Bridge API

`window.charmiq.appContent`

`window.charmiq.appState`

`window.charmiq.oauth`

`window.charmiq.mcp`

CharmIQ MCP Servers

Organization-Defined Servers

Explicit Connection (Dev/Testing)

Tool Call Results

Organization Tool Ceilings

Application Discovery

Observables

Next Steps

Server Alias	Purpose
`'vfs'`	Virtual file system — read/write documents, folders, app-content
`'agent'`	Run Charms, manage conversations
`'chat'`	Create and manage Chat documents; run completions with Charms
`'collection'`	Document collection management
`'docs'`	Browse and read CharmIQ documentation
`'generation'`	Generate images, video, audio via AI models
`'usage'`	Query credit balances and usage records
`'echo'`	Deterministic testing tool

Transport	When to Use
`'direct'`	Local servers, LAN servers, or servers with permissive CORS headers
`'proxy'`	Remote servers that block browser CORS (e.g. `googleapis.com`)

Auth Type	Description
`{ type: 'none' }`	No authentication
`{ type: 'platform' }`	CharmIQ platform token (for CharmIQ's own servers — rarely needed explicitly)
`{ type: 'oauth', providerUrl, scopes? }`	OAuth via provider URL — platform resolves Integration from Org config
`{ type: 'oauth', integrationId, scopes, app }`	OAuth via exact Integration ID — developer specifies directly