MCP servers

Documentation Index

Fetch the complete documentation index at: https://docs.poolside.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Overview

Use MCP (Model Context Protocol) 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. Unlike repositories, MCP servers let agents actively 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:

• Read-only reference data (use an indexed repository instead)
• Capabilities that should not be callable by agents
• Operations that cannot be safely constrained by permissions

​

How MCP servers work

1. Configure an MCP server in Poolside with the connection type and authentication it requires.
2. The server exposes one or more tools through the MCP protocol.
3. Those tools become available for assignment to agents.
4. When an agent invokes a tool during a run, Poolside sends the request to the MCP server.
5. The server runs the tool and returns the result to the agent.

​

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.

​

Choose a setup path

​

Personal MCP servers

A personal MCP server is one you configure in your own Poolside settings file. Poolside Assistant does not create these definitions. To add a personal MCP server, edit the settings file directly or use the Poolside Agent CLI.

​

Add a personal MCP server

Prerequisites

• The agent you are using allows custom MCP servers. If it does not, ask an administrator to turn on Allow users to connect to additional MCP servers for that agent.
• 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. After you add a personal MCP server, use it from Poolside Assistant or the Poolside Agent CLI.
   • Poolside Assistant
   • Poolside Agent CLI

   Open an agent session in Poolside Assistant, then click MCP.In the MCP dialog, select a server to review its status and available setup options. Depending on the server, you might need to complete authentication, update available inputs, or change whether the server is available to the current agent session.If the current agent does not allow custom MCP servers, you see a warning and your personal servers are unavailable in that session.

   Personal MCP servers from your settings file are available to pool and pool exec when the selected agent allows custom MCP servers.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.

​

Shared MCP servers

Use Poolside Console to create, configure, and manage MCP servers that can be shared across your organization. Administrators and users with the required MCP server permissions can create and manage these servers. Agents cannot use a shared MCP server until you explicitly enable it and grant tool access for that agent.

​

Add a shared MCP server

Prerequisites

• You have the Create MCP Server permission.
• You have connection and authentication details for the server you want to add.

Steps

1. In the Poolside Console, navigate to Tools > MCP Servers.
2. Click New MCP Server.
3. Optional: To prefill the form, copy the JSON configuration snippet from your MCP server’s documentation, then click Paste From Clipboard.
4. Enter a Name to identify the server.
5. Optional: Enter a Description.
6. Select a Connection type based on how you access the tool:
   • For remote HTTP-based tools or APIs, select Streamable HTTP or Server-Sent Events (SSE).
   • To run a local command or script as an MCP server, select Stdio (Local Process).
7. Configure connection details for the selected type. For a comparison of connection types, see Connection types.
   • Streamable HTTP or SSE
   • Stdio (Local Process)

   • Server URL: The base URL where the MCP server is hosted.
   • Custom Headers (optional): Use headers to pass authentication values or configuration details. For placeholder values, see Placeholders and dynamic variables.

   If the MCP server requires OAuth, it must support dynamic client registration (DCR). Poolside assigns the client ID automatically, so you do not need to configure credentials manually. For more information, see Authentication.

   • Command: The executable to run, such as node, python, or npx.
   • Arguments (optional): Arguments passed to the command, one per line.
   • Environment Variables (optional): Environment variables available to the process. For placeholder values, see Placeholders and dynamic variables.
8. Click Connect Server.

After creation, the MCP server appears in the Poolside Console, but agents cannot use it until you explicitly enable and permit it. Next steps After creating an MCP server:

1. Assign the MCP server to one or more agents.
2. Configure required authentication values.
3. Test tool invocation using an enabled agent.
4. Restrict tool access to only what the agent needs.

​

Edit a shared MCP server

Prerequisites

• You have the Manage MCP Servers permission.

Steps

1. In the Poolside Console, navigate to Tools > MCP Servers.
2. Select the MCP server.
3. Update the fields you want to change.
4. Click Save Changes.

​

Delete a shared MCP server

Deleting an MCP server removes it from all agents that reference it. Agents configured to use the deleted MCP server can no longer invoke its tools until you update the configuration. Prerequisites

• You have the Manage MCP Servers permission.

Steps

1. In the Poolside Console, navigate to Tools > MCP Servers.
2. Select the MCP server.
3. Click Delete.

​

Authentication

Some MCP servers require authentication in addition to the connection settings above. You configure that authentication on the MCP server, and Poolside handles it at runtime. Credentials are never exposed directly to agents. Depending on the server, authentication might involve API keys, tokens, environment variables, or OAuth-based sign-in. If authentication expires, you might be prompted to reauthenticate. For HTTP and SSE servers that require OAuth, Poolside supports dynamic client registration (DCR). Poolside assigns the client ID automatically during the OAuth flow, so you do not need to register credentials manually. DCR-enabled servers work across Poolside Chat, Poolside Assistant, the Poolside Agent CLI, and ACP-compatible clients. You might need to complete a separate authentication flow in each one.

​

Placeholders and dynamic variables

Shared MCP servers support placeholder variables whose values users provide when they run the agent. To use a placeholder, include it directly in the MCP server configuration where a value would normally appear. For personal MCP servers that you define in a settings file, use literal values or environment variables in the file instead. You can use placeholders in:

• Custom HTTP headers
• Environment variables
• Server URLs for HTTP- and SSE-based servers

Use the {{VAR_NAME}} syntax to define placeholder variables for values like API keys, user credentials, or environment-specific configuration. When an agent invokes the MCP server, Poolside prompts the user to provide values for any placeholders.

​

Access and security

Role-based permissions, agent configuration, and tool approvals determine who can access MCP servers and how agents can use them. MCP servers run with the permissions of their execution environment, so only connect servers that you trust. Access controls and tool permissions limit what agents can use, but they do not isolate or sandbox MCP server execution.

​

Approvals and sandbox behavior

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 and are auto-approved when the agent runs in a sandbox.
• HTTP and SSE servers run outside the sandbox and require explicit approval even when the agent runs in a sandbox.

​

Custom MCP server restrictions

When creating or editing an agent in Poolside Console, you can allow users to connect additional MCP servers by selecting Allow users to connect to additional MCP servers. If you turn off this option while users have custom MCP servers configured, the MCP server menu shows a warning. Agents cannot invoke those custom MCP servers until you turn the option on again.

​

Role-based permissions

Role permissions determine whether a user can create, use, or manage MCP servers. A user must have the Use MCP Servers permission to allow an agent to invoke tools exposed by an MCP server. For a complete list of permissions, see Permissions reference.

​

Agent access and tool permissions

Agents require explicit access to each MCP server.

• Enable each MCP server for the agents that need it.
• Grant tool-level access so agents can use all tools or a selected subset.

Agents can invoke an MCP server and tools only if:

• The agent has that MCP server and tools enabled.
• The user or API token running the agent has permission to use that MCP server.

Enabling an MCP server or tool for an agent does not give users permissions to use it.