MCP servers

​

Overview

Use Model Context Protocol (MCP) servers to connect Poolside agents to external tools and services. For more information, see the Model Context Protocol documentation. An MCP server acts as a tool endpoint that an agent can call. MCP servers let agents invoke tools, interact with APIs, and run operations in external systems. For a complete reference of supported settings.yaml keys, including mcp_servers, see Settings file reference.

​

When to use an MCP server

Use an MCP server when you want agents to:

• Invoke external tools or services
• Call APIs or interact with third-party systems
• Integrate with internal or custom tooling
• Perform specialized or domain-specific operations

Do not use an MCP server for:

• Static instructions or repeatable workflows. Use skills instead.
• Broad agent behavior that should apply to every task. Use AGENTS.md instructions instead.
• Operations that cannot be safely constrained by tool permissions and approvals.

​

Connection types

Each MCP server uses a single connection type, which determines how tools run and how Poolside communicates with them.

• Use Stdio (Local Process) to run an MCP server as a local process. This connection type is useful for local tools, scripts, or filesystem access.
• Use Streamable HTTP or Server-Sent Events (SSE) to connect to MCP servers over a URL. These connection types are typically used for hosted or remote services.

​

Add a personal MCP server

Personal MCP servers are defined in your Poolside settings file. Add them by editing settings.yaml directly or by using pool mcp add. Prerequisites

• You have the server details:
  • For a Stdio (Local Process) server, the command that starts the server.
  • For a Streamable HTTP or Server-Sent Events (SSE) server, the server URL and any required credentials.
• The pool CLI is installed, if you plan to use pool mcp add. See Install Poolside Agent CLI.

Steps

1. Add the server definition.
   • Edit the settings file
   • Use pool CLI

   Add an mcp_servers block to ~/.config/poolside/settings.yaml. This file stores personal MCP servers available across all your projects.

   To scope a server to the current project only, add it to .poolside/settings.local.yaml instead.

   If the file does not exist, create it first:

   mkdir -p ~/.config/poolside
   touch ~/.config/poolside/settings.yaml
   

   For a Stdio (Local Process) server, specify the command that starts the server:

   mcp_servers:
     <server-name>:
       command: <command>
       args:
         - <arg-1>
   

   For example:

   mcp_servers:
     filesystem:
       command: node
       args:
         - /path/to/filesystem-server.js
   

   For a Streamable HTTP or Server-Sent Events (SSE) server, specify the server URL:

   mcp_servers:
     <server-name>:
       transport:
         type: http
         url: https://<server-url>
         headers:
           - "Authorization: Bearer <api-token>"
   

   For example:

   mcp_servers:
     notion:
       transport:
         type: http
         url: https://mcp.notion.com/mcp
         headers:
           - "Authorization: Bearer <api-token>"
   

   For all available options, see MCP server configuration options.

   Use pool mcp add to add a server to ~/.config/poolside/settings.yaml.For a Stdio (Local Process) server:

   pool mcp add filesystem -- node /path/to/filesystem-server.js
   

   For a Streamable HTTP server:

   pool mcp add --transport http notion https://mcp.notion.com/mcp
   

   pool mcp add also supports --transport sse, --env, and --header. For all available options in the settings file, see MCP server configuration options.
2. Use the server from pool or pool exec. Personal MCP servers from your settings file are available to pool and pool exec. Example interactive session:
   pool --directory /path/to/project
   
   Example one-shot prompt:
   pool exec --prompt "Use the filesystem server to list files in this repository"
   
   For available pool mcp commands, see CLI reference.

​

MCP server configuration options

You can use the following configuration options in the settings file. Some options apply only to Stdio (Local Process) servers or only to Streamable HTTP or Server-Sent Events (SSE) servers.

​

Authentication

Some MCP servers require authentication in addition to the connection settings above. Depending on the server, authentication might involve API keys, tokens, environment variables, or OAuth-based sign-in. For HTTP and SSE servers, configure authentication values in the server definition, such as with headers or env. For local stdio servers, the server process runs with the permissions and environment available to the local agent host or sandbox.

​

Access and security

MCP servers run with the permissions of their execution environment, so only connect servers that you trust. Tool permissions and approvals limit what agents can use, but they do not isolate or sandbox MCP server execution by themselves. Approval behavior depends on the MCP server connection type and on whether the agent runs in a sandbox:

• Stdio MCP servers run inside the sandbox when the agent runs in a sandbox. In interactive pool and ACP sessions, stdio MCP tool calls are auto-approved when the session uses a sandbox.
• HTTP and SSE servers run outside the sandbox and require explicit approval even when the agent runs in a sandbox.

​

Related resources

• Settings file reference
• Tool permissions
• Poolside Agent CLI