---
title: "MCP Tools"
source: "https://docs.vertesiahq.com/agent-runner/mcp-tools"
markdown: "https://docs.vertesiahq.com/llms/agent-runner/mcp-tools.md"
---

# MCP Tools

Vertesia agents can use tools provided by external [MCP (Model Context Protocol)](https://modelcontextprotocol.io) servers. MCP servers are configured in [application manifests](/apps/tool-collections) and their tools become available to agents alongside built-in and custom tools.

## How It Works

1. An application manifest declares one or more MCP servers in its `tool_collections` array.
2. When the application is installed on a project, the MCP tools are discovered and made available to agents.
3. Tool names are prefixed with the configured `namespace` to avoid collisions (e.g., a tool named `search` with namespace `crm` becomes `crm_search`).
4. 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](/api/oauth-providers). 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](/apps/tool-collections) 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