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.

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'`	Run completions with your configured Charms
`'chat'`	Create and manage Chat documents; run completions with Charms
`'collection'`	Manage document collections
`'docs'`	Browse and read CharmIQ documentation
`'generation'`	Generate images, video, and audio via AI models
`'usage'`	Query credit balances and usage records
`'echo'`	Deterministic echo tool for testing

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

Explicit Connections

OAuth by Provider URL

No Authentication

Transport Options

Handling Tool Results

Tool Ceilings

Patterns

Next Steps