Skip to content

MCP Servers

oAI-Web can connect to external Model Context Protocol (MCP) servers and expose their tools to the agent.

What is MCP?

MCP is an open protocol for connecting AI models to external tools and data sources. An MCP server exposes a set of tools with JSON schemas. oAI-Web discovers these tools at startup and registers them as agent tools.

Setup

  1. Go to Settings → MCP Servers (admin) or Settings → MCP (non-admin)
  2. Click Add Server
  3. Fill in:
  4. Name — identifier used for tool namespacing (e.g. github)
  5. URL — the MCP server URL (e.g. http://localhost:3000/sse)
  6. Transport — sse (Server-Sent Events, default) or stdio
  7. API Key — optional, encrypted at rest
  8. Save

The server connection is established immediately. Tools are available in the next agent run.

Tool naming

MCP tools are namespaced to avoid collisions:

mcp__{servername}__{toolname}

For example, a server named github with a tool list_repos becomes mcp__github__list_repos.

Using MCP tools in agents

In the agent manager, you can declare MCP tools in allowed_tools: - Individual tool: mcp__github__list_repos - All tools from a server: mcp__github (wildcard — includes all mcp__github__* tools)

In interactive chat, all registered MCP tools are available automatically (subject to the user's role).

2nd Brain MCP server

oAI-Web includes a built-in MCP server that exposes the 2nd Brain to other AI clients. It runs as a sub-application at /brain-mcp/sse.

Tools exposed: - capture_thought — save a memory with embeddings - search_thoughts — semantic similarity search - browse_recent — list recent entries - get_stats — count and storage statistics

Authentication: The brain MCP server requires an API key (BRAIN_MCP_KEY in .env). Each user can have their own key stored in user_settings["brain_mcp_key"].

Configure other AI clients (e.g. Claude Desktop) to use http://your-server:8080/brain-mcp/sse with the appropriate API key.

Architecture notes

MCP server connections are managed by MCPManager in server/mcp_client/manager.py. It: 1. Loads all enabled server configs from the DB at startup 2. Connects to each server via SSE transport 3. Calls list_tools to discover available tools 4. Registers a MCPProxyTool instance for each tool 5. Deregisters tools when a server is disabled or deleted

If an MCP server is unavailable at startup, a warning is logged and the server is skipped. The connection is retried on the next startup.

Security

  • MCP tool calls are subject to the same audit logging as built-in tools
  • MCP servers can only be configured by admins (or by the user in their own settings)
  • Per-user MCP servers are only injected into that user's chat sessions
  • MCP API keys are stored encrypted (AES-256-GCM)