MCP Integration

OpenAlice runs two separate MCP (Model Context Protocol) servers for different purposes. Understanding the distinction is important.

Main MCP Server

Port: 3001 (configurable) Purpose: Exposes Alice's internal tools for AI consumption

The main MCP server is used by the Claude Agent SDK provider to deliver tools. When you use the default agent-sdk backend, tools flow from ToolCenter → MCP server → Claude Agent SDK.

This server is always active when a port is set — the Agent SDK provider depends on it.

Configuration in data/config/connectors.json:

{
  "mcp": { "port": 3001 }
}

You generally don't need to interact with the main MCP server directly. It's infrastructure for the AI provider.

MCP Ask

Port: Configurable, separate from main MCP Purpose: Lets external agents converse with Alice

MCP Ask exposes Alice's conversation ability — not her tools — to external agents. An external agent calls askWithSession to chat with Alice as a person, not to use her tools directly.

Why It's Separate

MCP Ask tools are deliberately NOT registered in ToolCenter. This prevents circular calls: Alice's own AI provider never sees the askWithSession tool, so she can't accidentally talk to herself.

Tools

Tool	Description
`askWithSession`	Send a message and get a response within a persistent session
`listSessions`	List all MCP Ask sessions
`getSessionHistory`	Read conversation history for a session

Usage

An external agent (e.g. another AI system) connects to the MCP Ask port and calls:

{
  "method": "tools/call",
  "params": {
    "name": "askWithSession",
    "arguments": {
      "message": "What's the current state of my portfolio?",
      "sessionId": "external-agent-1"
    }
  }
}

Alice processes the message through her full pipeline (session, compaction, tools, AI provider) and returns the response. Sessions are persistent — the sessionId is caller-managed, and Alice stores the conversation in data/sessions/mcp-ask__{sessionId}.jsonl.

Configuration

{
  "mcpAsk": {
    "enabled": false,
    "port": 3003
  }
}

MCP Ask is disabled by default. Enable it when you have external agents that need to interact with Alice.

Hot-Toggle

Like Telegram, MCP Ask can be enabled or disabled at runtime. Update connectors.json and the connector reconnect system handles the lifecycle.

Search Documentation