MCP Tools

Vertesia agents can use tools provided by external MCP (Model Context Protocol) servers. MCP servers are configured in application manifests and their tools become available to agents alongside built-in and custom tools.

How It Works

An application manifest declares one or more MCP servers in its tool_collections array.
When the application is installed on a project, the MCP tools are discovered and made available to agents.
Tool names are prefixed with the configured namespace to avoid collisions (e.g., a tool named search with namespace crm becomes crm_search).
If an MCP server requires OAuth, Vertesia manages that connection through the remote MCP connections flow in Studio Server. This is the control-plane API used to discover OAuth metadata, start authorization, exchange codes, check status, and disconnect remote MCP accounts.

OAuth Authentication

Many MCP servers require OAuth 2.0 authentication. Each user must connect their account before an agent can use the MCP tools on their behalf.

Connecting

Users connect from the new agent form in the Agent Runner interface. The form displays connect actions for any MCP tools that require authentication. Users must connect before starting the agent.

Behind the scenes, Vertesia treats these as remote MCP connections:

Vertesia looks up the installed app and target MCP collection.
If the collection is bound to a project-level OAuth Provider, Vertesia uses that provider configuration.
Otherwise, Vertesia can fall back to OAuth discovery on the remote MCP server itself.
Tokens are stored securely and refreshed automatically.

If a refresh token expires or is revoked, the user will need to reconnect.

Connection Modes

Remote MCP collections can authenticate in two main ways:

OAuth Provider-backed: the MCP collection is linked to a project-level OAuth Provider. This is the preferred path when you want explicit control over client ID, secret, scopes, and lifecycle.
Remote server discovery: if no provider is configured, Vertesia can discover OAuth metadata from the remote MCP server and follow that server's authorization flow.

For client_credentials providers, Vertesia can connect server-side without requiring an interactive browser flow.

Configuration

MCP servers are configured in application manifests, not in the Agent Runner directly. See MCP Servers for the full configuration reference including:

Required and optional fields
OAuth setup with project-level OAuth Providers, embedded oauth_config, and remote server discovery
Namespace configuration
Complete manifest examples