MCP Servers

Connect HiveMind OS to external tools and data sources through the Model Context Protocol (MCP). This guide walks you through adding servers, configuring transports, and scoping access.

Adding an MCP Server via UI

MCP servers are configured per persona — each persona gets its own set of integrations.

1. Open Settings → Personas and select (or create) a persona
2. Scroll to the MCP Servers section and click Add Server
3. Choose a transport type — stdio (local process), SSE (remote HTTP), or streamable-http (bidirectional HTTP)
4. Fill in the connection details (command, args, URL, environment variables)
5. Assign a channel classification (see below)
6. Click Save — HiveMind OS connects and discovers the server's tools automatically

Adding via YAML Config

You can also define MCP servers directly in your configuration file.

stdio Transport (Local Process)

Use stdio for servers that run as a local process on your machine. HiveMind OS spawns the process and communicates over stdin/stdout.

mcpServers:
  - id: filesystem
    transport: stdio
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]
    channel_class: local-only

SSE Transport (Remote HTTP)

Use sse for remote servers accessible over HTTP. Ideal for shared corporate tools or cloud-hosted services.

mcpServers:
  - id: remote-api
    transport: sse
    url: https://my-mcp-server.example.com/sse
    channel_class: internal

Streamable HTTP Transport

Use streamable-http for servers that support bidirectional HTTP streaming — a newer alternative to SSE with better connection handling.

mcpServers:
  - id: streaming-api
    transport: streamable-http
    url: https://my-mcp-server.example.com/mcp
    channel_class: internal

Environment Variables

Pass secrets via env — reference OS-level environment variables with the env: prefix so keys stay out of config files:

mcpServers:
  - id: github
    transport: stdio
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_TOKEN: env:GITHUB_TOKEN
    channel_class: internal

Popular MCP Servers

Great Servers to Try

Browse the full directory at MCP Servers Directory.

Server	What It Does	Install
filesystem	Enhanced file browsing and search	npx @modelcontextprotocol/server-filesystem
github	GitHub repos, PRs, and issues	npx @modelcontextprotocol/server-github
postgres	Query PostgreSQL databases	npx @modelcontextprotocol/server-postgres
brave-search	Web search via Brave	npx @modelcontextprotocol/server-brave-search
slack	Read and send Slack messages	npx @modelcontextprotocol/server-slack

Channel Classification

Classify Every MCP Server

Every MCP server must be assigned a channel_class. This controls what data the agent is allowed to send to it. A misconfigured classification can leak sensitive information to a public endpoint.

HiveMind OS applies the same data-classification rules to MCP servers as to model providers:

Channel Class	Accepts Data Up To
public	PUBLIC only
internal	PUBLIC, INTERNAL
private	PUBLIC, INTERNAL, CONFIDENTIAL
local-only	All levels (never leaves your machine)

Example: A filesystem server accessing local files should be local-only. A remote API you don't fully control should be internal or public depending on trust level.

Per-Persona Configuration

MCP servers are always configured per persona. Each persona has its own list of servers, so integrations are scoped to the agent that needs them — a security-focused reviewer doesn't get your Slack server.

id: user/data-analyst
name: Data Analyst
mcpServers:
  - id: postgres
    transport: stdio
    command: npx
    args: ["-y", "@modelcontextprotocol/server-postgres"]
    channel_class: internal
  - id: filesystem
    transport: stdio
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/data"]
    channel_class: local-only
allowed_tools:
  - mcp.postgres.*
  - filesystem.read

Only the servers listed in mcpServers are available to that persona. Each entry is a full MCP server configuration object. Omit the field (or use * in allowedTools) to grant access to all connected servers.

Troubleshooting

Problem	What to Check
Server not starting	Verify the command path is correct and the binary is installed (e.g., npx is on your PATH)
Tools not appearing	Restart the MCP connection from the persona's MCP Servers section — tool discovery runs at connect time
Permission errors	Check the server's channel_class — it may be too restrictive for the data the agent needs to send
Timeout issues	Increase the connection timeout in server settings; remote SSE servers may need longer initial handshakes

Beyond MCP: Connector Plugins

If you need more than what MCP provides — background sync loops, message emission, secret storage, configuration UIs — consider building a connector plugin. The plugin protocol is a superset of MCP, adding host APIs for messaging, events, and persistent storage on top of the standard MCP tool interface.

See the Plugin Development Guide to get started.

Learn More

• Tools & MCP — How built-in tools and MCP work together
• Privacy & Security — Data classification and channel enforcement
• Personas Guide — Scoping tools and servers per persona