# How Cherry Studio MCP Server Integration Works: A Complete Technical Guide

> Unlock Cherry Studio's MCP server integration. Discover its layered architecture for AI assistants invoking external tools via Redux prompt generation and runtime dispatch.

- Repository: [CherryHQ/cherry-studio](https://github.com/cherryhq/cherry-studio)
- Tags: deep-dive
- Published: 2026-02-27

---

**Cherry Studio's MCP server integration enables AI assistants to invoke external tools via the Model Context Protocol through a layered architecture involving Redux state management, prompt generation, and provider-agnostic runtime dispatch.**

Cherry Studio, an open-source AI client from the `cherryhq/cherry-studio` repository, implements the Model Context Protocol (MCP) to extend LLM capabilities beyond text generation. The Cherry Studio MCP server integration transforms external HTTP services into callable functions that large language models can invoke during conversations, creating a seamless bridge between AI reasoning and real-world tool execution.

## Architectural Layers of Cherry Studio MCP Integration

The integration follows a strict separation of concerns across seven distinct layers, each handling specific responsibilities from type validation to HTTP dispatch.

### Type Definitions and Validation

The foundation resides in [`src/renderer/src/types/mcp.ts`](https://github.com/cherryhq/cherry-studio/blob/main/src/renderer/src/types/mcp.ts), where **Zod schemas** define the shape of MCP servers and their install sources:

```typescript
export const MCPServerInstallSourceSchema = z.enum(['builtin','manual','protocol','unknown']).default('unknown')
export type MCPServerInstallSource = z.infer<typeof MCPServerInstallSourceSchema>

export interface MCPServer {
  id: string
  name: string
  type: 'inMemory' | 'http'
  installSource?: MCPServerInstallSource
  isTrusted?: boolean
}

```

Built-in servers are identified via `isBuiltinMCPServerName` in [`src/renderer/src/types/index.ts`](https://github.com/cherryhq/cherry-studio/blob/main/src/renderer/src/types/index.ts), distinguishing system tools like `memory` and `mcpAutoInstall` from user-added servers.

### State Management with Redux

The Redux slice in [`src/renderer/src/store/mcp.ts`](https://github.com/cherryhq/cherry-studio/blob/main/src/renderer/src/store/mcp.ts) manages the lifecycle of MCP servers:

```typescript
export const builtinMCPServers = [
  { name: BuiltinMCPServerNames.mcpAutoInstall, … },
  { name: BuiltinMCPServerNames.memory, … }
]

export const mcpSlice = createSlice({
  name: 'mcp',
  initialState: { mcpServers: [] as MCPServer[] },
  reducers: {
    setMCPServers(state, action) { state.mcpServers = action.payload },
    addMCPServer(state, action) { state.mcpServers.push(action.payload) }
  }
})

```

The `initializeMCPServers` function injects built-in servers at startup if they are missing from persisted state, ensuring core tools like the **hub server** are always available.

### Prompt Generation for LLM Tool Awareness

Before sending context to the LLM, [`src/renderer/src/utils/prompt.ts`](https://github.com/cherryhq/cherry-studio/blob/main/src/renderer/src/utils/prompt.ts) serializes available tools into the system prompt:

```typescript
export const AvailableTools = (tools: MCPTool[]) => {
  return tools.map(t => ({
    name: t.id,
    description: t.description,
    parameters: processSchemaForO3(t.inputSchema)
  }))
}

```

The `buildSystemPromptWithTools` function appends this JSON-encoded list to the system prompt, enabling **function calling** capabilities in the model.

### Provider-Agnostic Tool Mapping

[`src/renderer/src/utils/mcp-tools.ts`](https://github.com/cherryhq/cherry-studio/blob/main/src/renderer/src/utils/mcp-tools.ts) contains adapter functions that convert MCP tool definitions to provider-specific formats:

- **OpenAI**: `mcpToolsToOpenAIResponseTools` and `mcpToolsToOpenAIChatTools` create `function`-type tools
- **Anthropic**: `mcpToolsToAnthropicTools` builds `Tool` objects
- **Google Gemini**: `mcpToolsToGeminiTools`
- **AWS Bedrock**: `mcpToolsToAwsBedrockTools`

All mapping functions utilize `processSchemaForO3` from [`src/renderer/src/utils/mcp-schema.ts`](https://github.com/cherryhq/cherry-studio/blob/main/src/renderer/src/utils/mcp-schema.ts) to ensure strict O3 schema compliance required by OpenAI's API.

### Runtime Dispatch and HTTP Execution

The `callMCPTool` function in [`src/renderer/src/utils/mcp-tools.ts`](https://github.com/cherryhq/cherry-studio/blob/main/src/renderer/src/utils/mcp-tools.ts) serves as the runtime dispatcher:

```typescript
export async function callMCPTool(toolResponse: MCPToolResponse): Promise<MCPCallToolResponse> {
  const server = getMcpServerByTool(toolResponse.tool)
  if (!server) throw new Error(`Server not found: ${toolResponse.tool.serverName}`)

  // Short-circuit for built-in tools
  if (toolResponse.tool.serverName === BuiltinMCPServerNames.mcpAutoInstall) {
    // Auto-install logic
  }

  // Generic HTTP execution
  const resp = await fetch(`${server.baseUrl}/${toolResponse.tool.name}`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(toolResponse.arguments)
  })
  const data = await resp.json()
  return { toolResponse, result: data }
}

```

The function logs execution via `loggerService` and surfaces errors as toast notifications in the UI.

### Assistant-Level Server Resolution

[`src/renderer/src/services/ApiService.ts`](https://github.com/cherryhq/cherry-studio/blob/main/src/renderer/src/services/ApiService.ts) determines which MCP servers are active for a specific assistant:

```typescript
export function getMcpServersForAssistant(assistant: Assistant): MCPServer[] {
  const enabledMCPs = assistant.enabledMCPs?.length
    ? assistant.enabledMCPs
    : [hubMCPServer]
  return enabledMCPs
}

```

If no specific servers are configured, the assistant falls back to the **hub server**, ensuring baseline MCP functionality.

## The Complete MCP Tool Call Flow

Understanding the Cherry Studio MCP server integration requires following the complete lifecycle of a tool invocation:

1. **Assistant Configuration** – `enabledMCPs` is stored in the Redux state via `assistantSlice` during assistant creation or editing.

2. **Prompt Generation** – `buildSystemPromptWithTools` injects tool schemas from enabled servers into the system prompt sent to the LLM.

3. **LLM Decision** – The model returns a function call object (e.g., `{"name":"fetch","arguments":{"url":"https://api.example.com"}}`).

4. **Tool Resolution** – `openAIToolsToMcpTool` (or Anthropic/Gemini equivalents) maps the call name to an `MCPTool` object.

5. **Dispatch Execution** – `callMCPTool` receives the `MCPToolResponse`:
   - Built-in tools route through `callBuiltInTool`
   - External servers resolve via `getMcpServerByTool` and execute via HTTP POST to `${server.baseUrl}/${tool.name}`

6. **Result Handling** – The response normalizes to `MCPCallToolResponse` format and streams back to the chat interface as tool output.

## Practical Implementation Examples

### Registering a Custom MCP Server

Add external MCP servers to the Redux store using the `addMCPServer` action:

```typescript
import { addMCPServer } from '@renderer/store/mcp'

const myServer = {
  id: 'custom-mcp-1',
  name: 'MyRemoteMCP',
  type: 'http',
  baseUrl: 'https://my-mcp.example.com/api',
  installSource: 'manual',
  isTrusted: true,
  isActive: true
}

store.dispatch(addMCPServer(myServer))

```

This persists the server configuration in [`src/renderer/src/store/mcp.ts`](https://github.com/cherryhq/cherry-studio/blob/main/src/renderer/src/store/mcp.ts) and makes it available for assistant configuration.

### Invoking Tools from LLM Responses

Handle tool calls programmatically using the runtime dispatcher:

```typescript
import { callMCPTool } from '@renderer/utils/mcp-tools'

async function handleToolInvocation(toolResponse) {
  try {
    const result = await callMCPTool(toolResponse)
    // Result conforms to MCPCallToolResponse interface
    return result.result
  } catch (error) {
    console.error('Tool execution failed:', error)
    throw error
  }
}

```

The `callMCPTool` function in [`src/renderer/src/utils/mcp-tools.ts`](https://github.com/cherryhq/cherry-studio/blob/main/src/renderer/src/utils/mcp-tools.ts) handles both built-in and external server execution.

### Adding Built-in Tools

Built-in tools like `think` and `memory` bypass HTTP calls. They are identified by `isBuiltIn` in [`src/renderer/src/types/tool.ts`](https://github.com/cherryhq/cherry-studio/blob/main/src/renderer/src/types/tool.ts) and handled in `callBuiltInTool`:

```typescript
// Excerpt from callBuiltInTool implementation
if (toolResponse.tool.name === 'think' && typeof toolResponse.arguments === 'object') {
  const thought = toolResponse.arguments.thought
  // Process internal thought for chain-of-th reasoning
  return { content: [{ type: 'text', text: `Thought: ${thought}` }] }
}

```

These tools provide core functionality without external dependencies.

### Generating System Prompts with Tools

Construct LLM prompts that include available tools:

```typescript
import { buildSystemPromptWithTools } from '@renderer/utils/prompt'
import { getMcpServersForAssistant } from '@renderer/services/ApiService'

const assistant = /* retrieve from Redux store */
const servers = getMcpServersForAssistant(assistant)
const tools = servers.flatMap(s => s.tools ?? [])

const systemPrompt = buildSystemPromptWithTools(
  'You are a helpful assistant with access to external tools.',
  tools
)

```

The `buildSystemPromptWithTools` function in [`src/renderer/src/utils/prompt.ts`](https://github.com/cherryhq/cherry-studio/blob/main/src/renderer/src/utils/prompt.ts) serializes tool schemas for LLM consumption.

## Key Source Files Reference

| File | Role | Location |
|------|------|----------|
| [`src/renderer/src/types/mcp.ts`](https://github.com/cherryhq/cherry-studio/blob/main/src/renderer/src/types/mcp.ts) | MCP server and schema type definitions | [View on GitHub](https://github.com/cherryhq/cherry-studio/blob/main/src/renderer/src/types/mcp.ts) |
| [`src/renderer/src/store/mcp.ts`](https://github.com/cherryhq/cherry-studio/blob/main/src/renderer/src/store/mcp.ts) | Redux state management for servers | [View on GitHub](https://github.com/cherryhq/cherry-studio/blob/main/src/renderer/src/store/mcp.ts) |
| [`src/renderer/src/utils/mcp-tools.ts`](https://github.com/cherryhq/cherry-studio/blob/main/src/renderer/src/utils/mcp-tools.ts) | Provider mapping and runtime dispatch | [View on GitHub](https://github.com/cherryhq/cherry-studio/blob/main/src/renderer/src/utils/mcp-tools.ts) |
| [`src/renderer/src/utils/prompt.ts`](https://github.com/cherryhq/cherry-studio/blob/main/src/renderer/src/utils/prompt.ts) | System prompt construction with tools | [View on GitHub](https://github.com/cherryhq/cherry-studio/blob/main/src/renderer/src/utils/prompt.ts) |
| [`src/renderer/src/services/ApiService.ts`](https://github.com/cherryhq/cherry-studio/blob/main/src/renderer/src/services/ApiService.ts) | Assistant-level server resolution | [View on GitHub](https://github.com/cherryhq/cherry-studio/blob/main/src/renderer/src/services/ApiService.ts) |
| [`src/renderer/src/utils/mcp-schema.ts`](https://github.com/cherryhq/cherry-studio/blob/main/src/renderer/src/utils/mcp-schema.ts) | Schema processing for O3 compliance | [View on GitHub](https://github.com/cherryhq/cherry-studio/blob/main/src/renderer/src/utils/mcp-schema.ts) |
| [`src/renderer/src/types/tool.ts`](https://github.com/cherryhq/cherry-studio/blob/main/src/renderer/src/types/tool.ts) | Tool interface including `isBuiltIn` flag | [View on GitHub](https://github.com/cherryhq/cherry-studio/blob/main/src/renderer/src/types/tool.ts) |

## Summary

Cherry Studio MCP server integration operates through a sophisticated multi-layered architecture:

- **Type-safe configuration** via Zod schemas in [`src/renderer/src/types/mcp.ts`](https://github.com/cherryhq/cherry-studio/blob/main/src/renderer/src/types/mcp.ts) validates both built-in and custom servers
- **Centralized state management** through Redux in [`src/renderer/src/store/mcp.ts`](https://github.com/cherryhq/cherry-studio/blob/main/src/renderer/src/store/mcp.ts) persists server configurations and handles built-in injection at startup
- **Dynamic prompt generation** in [`src/renderer/src/utils/prompt.ts`](https://github.com/cherryhq/cherry-studio/blob/main/src/renderer/src/utils/prompt.ts) serializes tool schemas into LLM system prompts
- **Provider abstraction** via [`src/renderer/src/utils/mcp-tools.ts`](https://github.com/cherryhq/cherry-studio/blob/main/src/renderer/src/utils/mcp-tools.ts) converts MCP definitions to OpenAI, Anthropic, Gemini, and Bedrock formats
- **Unified runtime dispatch** through `callMCPTool` handles both built-in implementations and external HTTP requests to MCP servers

This design enables seamless extension of AI assistant capabilities while maintaining strict type safety and provider compatibility.

## Frequently Asked Questions

### What is the Model Context Protocol (MCP) in Cherry Studio?

The Model Context Protocol (MCP) is an open standard that Cherry Studio implements to allow AI assistants to discover and invoke external tools. In Cherry Studio, MCP servers are HTTP services that expose functions—such as web fetching, memory storage, or custom business logic—that the LLM can call during conversations to retrieve real-time data or perform actions.

### How does Cherry Studio handle different LLM providers for MCP tools?

Cherry Studio uses provider-specific adapter functions in [`src/renderer/src/utils/mcp-tools.ts`](https://github.com/cherryhq/cherry-studio/blob/main/src/renderer/src/utils/mcp-tools.ts) to translate MCP tool definitions into formats required by each LLM API. The codebase includes `mcpToolsToOpenAIResponseTools` and `mcpToolsToOpenAIChatTools` for OpenAI, `mcpToolsToAnthropicTools` for Claude, `mcpToolsToGeminiTools` for Google, and `mcpToolsToAwsBedrockTools` for AWS. All adapters process schemas through `processSchemaForO3` to ensure compatibility.

### Can I add my own custom MCP servers to Cherry Studio?

Yes, you can register custom MCP servers through the Redux store using the `addMCPServer` action in [`src/renderer/src/store/mcp.ts`](https://github.com/cherryhq/cherry-studio/blob/main/src/renderer/src/store/mcp.ts). You must provide a unique ID, server name, type (typically `'http'`), base URL, and installation source. Once registered, the server appears in the MCP settings UI at `src/renderer/src/pages/settings/MCPSettings/*` where you can activate it for specific assistants.

### What built-in MCP tools does Cherry Studio provide?

Cherry Studio includes several built-in MCP servers that operate without external HTTP calls. These include the **hub server** (default fallback for assistants), **mcpAutoInstall** (handles automatic tool installation), and **memory** (provides persistent storage across conversations). Built-in tools are identified by the `isBuiltIn` flag in [`src/renderer/src/types/tool.ts`](https://github.com/cherryhq/cherry-studio/blob/main/src/renderer/src/types/tool.ts) and are executed through `callBuiltInTool` in [`src/renderer/src/utils/mcp-tools.ts`](https://github.com/cherryhq/cherry-studio/blob/main/src/renderer/src/utils/mcp-tools.ts) rather than being dispatched to external endpoints.