---
title: "MCP Servers"
source: https://docs.autohand.ai/working-with-autohand-code/mcp-servers
---

# MCP Servers

The Model Context Protocol (MCP) extends Autohand with external tools from any MCP-compatible server. Connect databases, APIs, documentation providers, and more through a standardized interface supporting stdio, SSE, and Streamable HTTP transports.

## 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

**Tip:** Use `/mcp list` during a session to see all configured servers and their connection status.

## Quick start

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

``` bash
# 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:

| Transport | Protocol | Use case |
|---|---|---|
| stdio | Spawns a child process, JSON-RPC 2.0 over stdin/stdout | Local tools, CLI wrappers, language servers |
| sse | HTTP Server-Sent Events connection | Remote servers with streaming support |
| http | MCP Streamable HTTP with session tracking and dual-format response handling | Cloud-hosted MCP services, APIs with authentication |

## 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

``` json
{
  "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

| Field | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | Unique server identifier |
| transport | "stdio" / "sse" / "http" | Yes | Connection type |
| command | string | stdio only | Command to start the server process |
| args | string[] | No | Command arguments |
| url | string | sse/http only | Server endpoint URL |
| headers | object | No | Custom HTTP headers (auth tokens, API keys) |
| env | object | No | Environment variables for the server process |
| autoConnect | boolean | No (default: true) | Connect on startup |

## CLI commands

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

### Add a server

``` bash
# 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

``` bash
# List all configured servers
autohand mcp list

# Remove a server
autohand mcp remove database
```

### Command reference

| Command | Description |
|---|---|
| autohand mcp add <name> <command...> | Add a stdio server with the given command |
| autohand mcp add -t sse <name> <url> | Add an SSE server at the given URL |
| autohand mcp add -t http <name> <url> | Add an HTTP server at the given URL |
| autohand mcp list | List all configured MCP servers |
| autohand mcp remove <name> | Remove a server by name |

### Flags

| Flag | Description |
|---|---|
| -t, --transport <type> | Set transport type: stdio (default), sse, or http |
| --header <key: value> | Add a custom HTTP header (repeatable) |
| -e, --env <KEY=VALUE> | Set an environment variable for the server process (repeatable) |

## Slash commands

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

| Command | Description |
|---|---|
| /mcp | Interactive server toggle list (enable/disable with arrow keys) |
| /mcp add | Browse and install from community MCP registry |
| /mcp add <name> | Search community registry for a server by name |
| /mcp add <name> <cmd> [args] | Add a custom stdio server to config and connect |
| /mcp add --transport http <name> <url> | Add a custom HTTP server with headers |
| /mcp connect <name> | Connect to a configured server |
| /mcp disconnect <name> | Disconnect from a running server |
| /mcp list | List all tools from connected servers |
| /mcp remove <name> | Remove a server from config |

**Note:** `/mcp install` still works as a backward-compatible alias for `/mcp add`.

## 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.

``` text
# 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

``` json
{
  "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

**Tip:** Set `"autoConnect": false` for servers you only need occasionally. Connect them manually with `/mcp connect` when needed.

## Frequently asked questions

### What is MCP in Autohand CLI?

MCP (Model Context Protocol) is an open standard that lets Autohand connect to external tool servers. Each MCP server exposes tools that the agent can use during a session, such as database queries, web searches, or design system lookups. Autohand supports three transports: stdio, SSE, and Streamable HTTP.

### How do I add an MCP server to Autohand?

Run /mcp add inside a session to browse the curated registry or add a custom server. From the command line, use autohand mcp add mydb npx -y @mcp/postgres for a stdio server, or autohand mcp add -t http api https://api.example.com/mcp for HTTP. Servers are saved in ~/.autohand/config.json.

### What MCP servers are available for Autohand?

The built-in registry includes servers for GitHub, PostgreSQL, Brave Search, Slack, Context7 (documentation lookup), Firecrawl (web scraping), Figma (design to code), and E2B (sandboxed code execution). Community servers are also available. Run /mcp add without arguments to browse the full list.