MCP servers

​

Overview

Use MCP (Model Context Protocol) servers to connect agents to external tools and services. MCP is a standardized protocol for connecting AI clients to external tools. In Poolside, you configure MCP servers as the tool endpoints your agents can call. Unlike knowledge bases, MCP servers let agents actively call tools, interact with APIs, and run operations in external systems.

​

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 a knowledge base 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 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.

​

Agent tool invocation

When you enable an MCP server for an agent, the agent can:

• Invoke permitted tools exposed by the server
• Pass runtime inputs and resolved placeholders
• Use tool results to inform responses or workflows

During a run, the agent can call only the tools it is permitted to use. If it attempts to call a tool outside that access, the request is rejected.

​

Connection types

Each MCP server uses a single connection type, which determines how tools run and how Poolside communicates with them. The table below compares the supported connection types and when to use each one.

​

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 MCP servers run outside the sandbox and require explicit approval even when the agent runs in a sandbox.

This is because the main client executes HTTP and SSE MCP requests rather than the sandboxed client.

​

Custom MCP server restrictions

When creating or editing an agent in the 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, and
• 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.

​

Placeholders and dynamic variables

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. 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. When an agent invokes the MCP server, Poolside prompts the user to provide values for any placeholders. Common use cases include:

• API keys or tokens
• User-specific credentials
• Environment-specific configuration values

​

Authentication

Some MCP servers require authentication beyond transport-level configuration. 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.

​

Create an MCP server

Prerequisites

• You have the Create MCP Servers 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: Paste a JSON configuration snippet to prefill the form.
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.
   • Streamable HTTP or SSE
   • Stdio (Local Process)

   If you selected Streamable HTTP or Server-Sent Events (SSE), provide the following:

   • Server URL: The base URL where the MCP server is hosted.
   • Custom Headers (optional): Use headers to pass authentication values or configuration details. Use the {{VAR_NAME}} syntax to create placeholder variables provided by users of the agent.

   If you selected Stdio (Local Process), provide the following:

   • 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. Use the {{VAR_NAME}} syntax to create placeholder variables provided by users of the agent.
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.

​

Delete an 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. Steps

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