Connect via MCP

proto connects to external tools and data sources through the Model Context Protocol (MCP). MCP servers give proto access to databases, APIs, file systems, and any custom tooling you expose.

Add your first server

proto mcp add --transport http my-server http://localhost:3000/mcp

Then open a session and ask proto to use tools from that server. MCP tools appear automatically in the model's tool list.

Configuration scopes

• Project (default): .proto/settings.json
• User: ~/.proto/settings.json (add --scope user to proto mcp add)

Transport types

Transport	Use when	Key field
http	Remote services, cloud MCP servers	httpUrl
sse	Legacy servers (Server-Sent Events)	url
stdio	Local process (scripts, CLIs, Docker)	command + args

Prefer HTTP over SSE when a server supports both.

Configure via settings.json

Stdio (local process)

{
  "mcpServers": {
    "pythonTools": {
      "command": "python",
      "args": ["-m", "my_mcp_server"],
      "cwd": "./mcp-servers/python",
      "env": { "DATABASE_URL": "$DB_CONNECTION_STRING" },
      "timeout": 15000
    }
  }
}

HTTP (remote)

{
  "mcpServers": {
    "httpServer": {
      "httpUrl": "http://localhost:3000/mcp",
      "headers": { "Authorization": "Bearer your-token" },
      "timeout": 5000
    }
  }
}

SSE (legacy)

{
  "mcpServers": {
    "sseServer": {
      "url": "http://localhost:8080/sse",
      "timeout": 30000
    }
  }
}

Server configuration options

Property	Type	Description
command	string	Executable path (stdio)
url	string	SSE endpoint URL
httpUrl	string	HTTP streaming endpoint URL
args	string[]	Arguments for stdio command
env	object	Environment variables ($VAR syntax supported)
cwd	string	Working directory for stdio
timeout	number	Request timeout in ms (default: 600,000)
trust	boolean	Skip all confirmation prompts for this server
includeTools	string[]	Allowlist of tool names from this server
excludeTools	string[]	Denylist of tool names (excludeTools wins over includeTools)
headers	object	HTTP headers for url/httpUrl transports

Safety controls

Trust a server — skip confirmations (use sparingly):

{ "trust": true }

Filter tools per server:

{
  "mcpServers": {
    "myServer": {
      "command": "my-server",
      "includeTools": ["safe_tool", "read_data"],
      "excludeTools": ["delete_all"]
    }
  }
}

Global allow/deny lists:

{
  "mcp": {
    "allowed": ["my-trusted-server"],
    "excluded": ["experimental-server"]
  }
}

proto mcp CLI

proto mcp                                          # open management dialog
proto mcp add <name> <command-or-url> [args...]    # add a server
proto mcp add --transport http <name> <url>        # add HTTP server
proto mcp add --scope user <name> ...              # add to user scope
proto mcp remove <name>                            # remove a server
proto mcp list                                     # list configured servers

Common add flags:

Flag	Description
-s, --scope	project (default) or user
-t, --transport	stdio, sse, http
-e, --env	Environment variable (KEY=value)
-H, --header	HTTP header
--timeout	Timeout in ms
--trust	Trust the server
--include-tools	Comma-separated allowlist
--exclude-tools	Comma-separated denylist

Server instructions

MCP servers can embed usage guidance in their initialize response via an instructions field. proto automatically appends these to the system prompt:

# MCP Server Instructions

## MCP Server: my-server

<instructions from the server>

If you are building an MCP server, implement the instructions field to guide the model without requiring users to write AGENTS.md entries.

Troubleshooting

Symptom	Fix
Server shows "Disconnected"	Verify the URL/command is correct; increase timeout
Stdio server fails to start	Use absolute path for command; check cwd and env
Env vars don't resolve in JSON	Ensure the variable exists in the shell that runs proto