MCP Servers

Overview

MCP is an open, industry-standard protocol that lets language models invoke external tools. Autohand acts as an MCP client, connecting to one or more MCP servers that each expose a set of tools. Once connected, the agent can discover and call those tools just like built-in capabilities.

Autohand supports three transport mechanisms for communicating with MCP servers:

• stdio – spawns a local child process and communicates over stdin/stdout
• sse – connects to a remote server via HTTP Server-Sent Events
• http – uses the MCP Streamable HTTP protocol with session tracking

Quick start

Add an MCP server from the command line and start using its tools immediately:

# Add an stdio server
autohand mcp add database npx -y @modelcontextprotocol/server-postgres

# Add an HTTP server with auth headers
autohand mcp add --transport http context7 https://mcp.context7.com/mcp \
  --header "CONTEXT7_API_KEY: your-key"

# List configured servers
autohand mcp list

Once a server is added, its tools become available to the agent automatically. Tools are namespaced by server name to avoid collisions (e.g., mcp__database__query).

Transports

Each transport handles communication between Autohand and the MCP server differently. Choose the one that matches your server's capabilities:

Configuration

MCP servers are configured in ~/.autohand/config.json under the mcp.servers key. You can also use project-level .autohand/config.json for per-project servers.

Full example

{
  "mcp": {
    "servers": [
      {
        "name": "database",
        "transport": "stdio",
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-postgres"],
        "env": {
          "DATABASE_URL": "postgresql://localhost:5432/mydb"
        },
        "autoConnect": true
      },
      {
        "name": "docs",
        "transport": "sse",
        "url": "https://docs-mcp.example.com/sse",
        "autoConnect": true
      },
      {
        "name": "context7",
        "transport": "http",
        "url": "https://mcp.context7.com/mcp",
        "headers": {
          "CONTEXT7_API_KEY": "your-key"
        },
        "autoConnect": true
      }
    ]
  }
}

Configuration fields

CLI commands

Manage MCP servers non-interactively from the command line. Useful for scripting and CI environments.

Add a server

# stdio server (default transport)
autohand mcp add database npx -y @modelcontextprotocol/server-postgres

# SSE server
autohand mcp add --transport sse docs https://docs-mcp.example.com/sse

# HTTP server with custom headers
autohand mcp add --transport http context7 https://mcp.context7.com/mcp \
  --header "CONTEXT7_API_KEY: your-key"

# stdio server with environment variables
autohand mcp add database npx -y @modelcontextprotocol/server-postgres \
  -e DATABASE_URL=postgresql://localhost:5432/mydb

List and remove

# List all configured servers
autohand mcp list

# Remove a server
autohand mcp remove database

Command reference

Flags

Slash commands

Manage MCP servers interactively during a session using the /mcp slash command.

Tool naming

Tools from MCP servers are namespaced using the pattern mcp__<server>__<tool> to avoid collisions with built-in tools and tools from other servers.

# A tool called "query" from a server named "database"
mcp__database__query

# A tool called "resolve-library-id" from a server named "context7"
mcp__context7__resolve-library-id

This naming convention ensures that even if two servers expose tools with the same name, they remain distinct and unambiguous to the agent.

Streamable HTTP transport

The http transport implements the MCP Streamable HTTP specification, designed for cloud-hosted MCP services that need session management and flexible response formats.

How it works

• Sends requests with Accept: application/json, text/event-stream to support both response formats
• Tracks the Mcp-Session-Id header across requests for session continuity
• Parses both direct JSON and SSE-wrapped responses transparently
• Supports custom headers for authentication (API keys, bearer tokens)

Example configuration

{
  "mcp": {
    "servers": [
      {
        "name": "cloud-tools",
        "transport": "http",
        "url": "https://mcp.example.com/mcp",
        "headers": {
          "Authorization": "Bearer sk-your-token"
        }
      }
    ]
  }
}

The HTTP transport is the best choice when connecting to remote MCP services that require authentication and session persistence.

Non-blocking startup

MCP servers connect asynchronously in the background when Autohand starts. This means the agent is ready to accept instructions immediately without waiting for all servers to finish connecting.

How it works

• On startup, connection attempts for all configured servers are fired in parallel
• Tools become available as each server comes online
• If the agent invokes a tool before its server has finished connecting, Autohand performs a just-in-time wait for that specific server
• Failed connections are logged but do not block the agent from starting

Frequently asked questions