MCP Server Integration

Model Context Protocol (MCP) lets you connect a Verly agent to external tools through a hosted MCP server. Instead of creating one custom API action at a time, you can attach a single MCP endpoint and expose a full set of tools to your agent.

This is ideal when you want your agent to work with systems like CRMs, ticketing platforms, developer tools, internal APIs, or workflow platforms through a standard tool interface.

How MCP Works in Verly

When a user asks your agent to perform a task, Verly can call a tool on your connected MCP server in the background. The MCP server executes the request, returns structured data, and the agent uses that result to generate a final response.

In practice, the flow looks like this:

1. A user asks for something that requires an external system.
2. Verly chooses the relevant MCP tool based on the tool name and description.
3. Verly sends a JSON request to your MCP server over HTTPS.
4. Your MCP server returns a JSON response.
5. The agent uses that response to answer the user.

This gives your agent live access to business systems without hardcoding every integration directly inside Verly.

Compatibility Requirements

Verly currently supports remote HTTP-based MCP servers. Your server must meet all of the requirements below.

If your MCP server satisfies these conditions, it should work with Verly.

Supported transports

Why Streamable HTTP is required

Verly sends standard HTTPS POST requests with JSON bodies and expects JSON responses back. This keeps MCP calls stateless and reliable inside production chat workflows.

Older SSE-based MCP servers rely on long-lived streaming connections. Verly does not use that transport for tool execution, so SSE-only servers are not compatible.

Authentication Options

Verly supports these authentication patterns for MCP servers:

OAuth redirect flows are not handled automatically during setup. If your MCP provider uses OAuth, complete that connection outside Verly first and use the resulting access token or API key in the MCP configuration.

Setting Up an MCP Server

When adding an MCP server in Verly, you will usually configure the following:

Recommended setup flow

1. Open the agent you want to extend with external tools.
2. Go to your tools or integrations area and add a new MCP server.
3. Enter the hosted MCP endpoint URL.
4. Configure the required authentication headers.
5. Test the connection and confirm the server exposes the expected tools.
6. Save the integration and verify the tool behavior in the Playground.

How to Evaluate Compatibility

Before connecting any MCP server, look for these signals.

Good signs

• The docs mention Streamable HTTP or the 2025-03-26 MCP protocol.
• The server exposes a single hosted HTTPS endpoint such as https://mcp.example.com/mcp.
• Authentication uses a bearer token or API key in request headers.
• The server is always-on and does not depend on a local process running on your laptop.

Red flags

• The docs only mention SSE transport or the 2024-11-05 protocol.
• Setup requires commands like npx, uvx, or docker run on your local machine.
• The server is meant for Claude Desktop or another local MCP client.
• It depends on an interactive browser-based auth flow that cannot be converted into a reusable token.

Examples

Common compatible server types

• Managed MCP platforms that host integrations behind a single MCP endpoint
• Vendor-hosted MCP servers for products like CRMs, project management tools, and internal knowledge systems
• Custom self-hosted MCP servers that implement the Streamable HTTP transport

Common incompatible server types

• Local MCP servers designed for desktop apps
• Servers that only support stdio
• Servers that only support HTTP + SSE
• MCP packages that require local runtime commands and do not expose a remote endpoint

If you need to use an older server, you may be able to place a proxy in front of it that exposes a compatible Streamable HTTP endpoint.

Best Practices

Keep tool descriptions clear

The agent chooses tools based on their names and descriptions. Make sure your MCP server exposes tools with clear, narrow descriptions so Verly can route requests accurately.

Prefer focused toolsets

A small set of well-defined tools performs better than a giant server with overlapping capabilities. Group tools by business function where possible.

Protect secrets

Store bearer tokens and API keys in Verly's secure integration settings. Never include credentials in tool descriptions, prompts, or agent-visible instructions.

Test failures on purpose

Verify how your agent behaves when the MCP server returns an auth error, timeout, or empty result. This helps you design better fallbacks and escalation rules.

Quick Checklist

Before connecting your MCP server, confirm that:

• The server has a reachable HTTPS endpoint
• It supports Streamable HTTP using the 2025-03-26 MCP transport
• It returns plain JSON responses
• Authentication works with a bearer token or API key header
• The server is hosted and always available
• You have tested the tools in Playground after connecting

If all of these are true, your MCP server is ready to use with Verly.