Applications can connect to MCP servers and call their tools directly, using the same protocol your Charms use to reach external services. CharmIQ handles credentials, transport, and authentication on behalf of your iframe — your code never touches tokens or connection management.

 are CharmIQ's built-in MCP servers. They're pre-connected with authentication. You call their tools directly, without a 

 are configured by your Organization administrator in the Integration settings. Your Application discovers them via 

 and connects using their platform-assigned ID. The URL, authentication, and tool permissions are all managed at the Organization level — your Application just uses them.

 are servers your Application connects to directly, providing the URL and authentication config itself. This is the right approach for development, testing, or servers that aren't available as Organization-defined.

 returns everything: CharmIQ servers and any Organization-defined servers your admin has configured.

const servers = await window.charmiq.mcp.listServers();

// Every server descriptor:
// { id, name, isPlatform, allowedTools? }

const platformServers = servers.filter(s => s.isPlatform);
const orgServers = servers.filter(s => !s.isPlatform);

 and are always present. Organization-defined servers have an 

 array when the admin has restricted which tools are accessible — if it's absent, all tools are permitted.

 call needed. Use the server name as the alias directly.

// List what's available on a platform server
const tools = await window.charmiq.mcp.listTools('vfs');

// Call a tool
const result = await window.charmiq.mcp.callTool('vfs', 'search_documents', {
  query: 'Q3 budget',
  limit: 10,
});

Discover the server ID, connect with a local alias, then call tools.

// 1. Discover
const servers = await window.charmiq.mcp.listServers();
const bq = servers.find(s => s.name.includes('BigQuery'));

// 2. Connect — first argument is your local alias
await window.charmiq.mcp.connect('bigquery', { mcpServerId: bq.id });

// 3. List tools (filtered by Organization's allowedTools)
const tools = await window.charmiq.mcp.listTools('bigquery');

// 4. Call
const result = await window.charmiq.mcp.callTool('bigquery', 'execute_sql', {
  query: 'SELECT * FROM `project.dataset.orders` WHERE status = "open" LIMIT 50',
});

// 5. Disconnect when done
await window.charmiq.mcp.disconnect('bigquery');

 in this example) is a name you choose. You use it in all subsequent calls until you disconnect.

A folder- or document-based Application must include every MCP capability it uses in the manifest's 

. An inline Application or a raw Source Application declares the same scopes on its 

, not merely the JavaScript alias passed to 

 are not valid MCP call-site declarations.

 for that connection. Prefer exact declarations. A portable Application that discovers Organization servers whose IDs are not known at authoring time may declare 

; because wildcard declarations are not pre-granted in the ask-once batch, the User still decides each concrete Organization server when first used.

For servers not in the Organization's configuration. Typically used for development and testing.

The platform resolves the Integration from your Organization config using the provider URL.

await window.charmiq.mcp.connect('gh', {
  url: 'https://github.com/mcp',
  transport: 'proxy',
  auth: {
    type: 'oauth',
    providerUrl: 'https://github.com',
    scopes: ['repo:read'],
  },
});

await window.charmiq.mcp.connect('local', {
  url: 'http://localhost:8080/mcp',
  transport: 'direct',
  auth: { type: 'none' },
});

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

const result = await window.charmiq.mcp.callTool('bigquery', 'execute_sql', { query });

if (result.isError) {
  console.error('Tool error:', result.content[0].text);
  return;
}

const rows = JSON.parse(result.content[0].text);
renderTable(rows);

Organization-defined servers may have an 

, your Application cannot call any other tool on that server regardless of what the MCP server advertises. 

 already returns only the permitted tools — you don't need to filter manually.

If your Application needs a tool that isn't in the ceiling, the resolution is an admin configuration change, not a code change.

 — Organization admin guide: configuring MCP servers and OAuth providers that Applications can connect to.

 — Authenticating with external APIs directly (not via MCP) using the Application Bridge.

How Applications connect to MCP servers — CharmIQ's built-in servers, Organization-defined servers, and explicit connections.

Alias	What It Does
`'vfs'`	Read and write documents, folders, and app-content in the workspace
`'agent'`	Manage Charms — System Prompt and LLM configuration
`'application'`	Build Applications into runnable artifacts
`'chat'`	Create and manage Chat documents; run completions with Charms
`'collection'`	Manage Collections of documents and assets
`'context'`	Manage a document's Reference Materials — the documents, assets, and folders a Charm works against
`'docs'`	Browse and read CharmIQ documentation
`'generation'`	Generate images, video, audio, and music via AI models
`'git'`	Clone, pull, commit, push for git-backed Folders
`'usage'`	Query credit balances and usage records
`'workspace'`	Ask a Charm a question inside a Workspace document
`'echo'`	Deterministic echo tool for testing

Operation	Required Scope
`listServers()`	`mcp.discover`
Use a pre-connected CharmIQ server	`mcp.platform.{serverName}`
Connect to or use an Organization-defined server	`mcp.org.{serverId}`
Connect to or use an explicit server	`mcp.adhoc.{connectionName}`
Connect to an explicit server with OAuth	`mcp.adhoc.{connectionName}` and `oauth.token`

Transport	When to Use
`'direct'`	Browser connects directly. Use for local servers or servers with permissive CORS.
`'proxy'`	Traffic routes through CharmIQ's cloud function. Use for remote servers that block browser CORS.

Developer | MCP in Applications

Three Types of Servers

Discovering What's Available

Using CharmIQ MCP Servers

Using Organization-Defined MCP Servers

Declaring MCP Scopes

Explicit Connections

OAuth by Provider URL

No Authentication

Transport Options

Handling Tool Results

Tool Ceilings

Patterns

Next Steps