MCP Servers

MCP (Model Context Protocol) servers connect external tools to your Vertesia applications. Agents can then use the tools provided by these servers during execution.

For custom HTTP tool servers built with the Vertesia Tools SDK, use the endpoint field in your app manifest instead — tools are discovered automatically from the endpoint URL.

Quick Start

Add an MCP server to your app manifest's tool_collections array:

{
  "name": "my-app",
  "tool_collections": [
    {
      "type": "mcp",
      "url": "https://mcp.example.com/v1",
      "name": "example-tools",
      "description": "Tools from Example service",
      "namespace": "example",
      "auth": "oauth"
    }
  ]
}

MCP Configuration Fields

Field	Type	Required	Description
`type`	`string`	Yes	Must be `"mcp"`.
`url`	`string`	Yes	The MCP server URL.
`name`	`string`	Yes	Display name for the tool collection.
`description`	`string`	Yes	Human-readable description of the tools provided.
`namespace`	`string`	Yes	Prefix added to tool names to avoid collisions (e.g., `example_search`).
`auth`	`string`	No	Authentication type. Set to `"oauth"` for OAuth-protected servers.
`oauth_app`	`string`	No	Name of an OAuth Application providing the client ID and secret. Required when the MCP server does not support dynamic client registration. Requires `auth: "oauth"`.

Namespacing

The namespace field is prepended to all tool names from the MCP server. For example, if the server exposes a tool named search and the namespace is crm, the agent sees it as crm_search. This prevents name collisions when multiple MCP servers are configured.

OAuth Authentication

Some MCP servers require OAuth 2.0 authentication. Vertesia handles the full OAuth flow including token storage and automatic refresh.

If the MCP server supports dynamic client registration, Vertesia registers automatically and no OAuth Application is needed — just set auth: "oauth" in the collection. For servers that do not support dynamic client registration (i.e., they require a pre-configured client ID and secret), you must create an OAuth Application and reference it via the oauth_app field.

Step 1: Create an OAuth Application

Go to Project Settings > OAuth Apps and click Create. Fill in:

Field	Description
Name	Kebab-case identifier (e.g., `my-crm-oauth`). Used to reference the app in manifests.
Display Name	Human-readable label shown in the UI.
Client ID	OAuth client identifier from the provider.
Client Secret	OAuth client secret (encrypted at rest). Optional for public clients using PKCE.
Default Scopes	Space-separated OAuth scopes (e.g., `read write`).
Use PKCE	Enable PKCE (Proof Key for Code Exchange). Enabled by default.
Authorization Endpoint	OAuth authorize URL. Optional — auto-discovered from the MCP server's `.well-known/oauth-authorization-server` metadata when omitted.
Token Endpoint	OAuth token exchange URL. Optional — auto-discovered when omitted.
Revocation Endpoint	Token revocation URL. Optional.

For MCP servers that publish OAuth metadata at .well-known/oauth-authorization-server, you only need to provide the Client ID (and Client Secret if required by the provider). The authorization and token endpoints are discovered automatically.

See the OAuth Applications API reference for programmatic management.

Step 2: Reference the OAuth App in the Manifest

Add the auth and oauth_app fields to the MCP collection:

{
  "tool_collections": [
    {
      "type": "mcp",
      "url": "https://mcp.my-crm-provider.com",
      "name": "My CRM",
      "description": "CRM tools for contacts and deals",
      "namespace": "crm",
      "auth": "oauth",
      "oauth_app": "my-crm-oauth"
    }
  ]
}

The oauth_app value must match the Name of the OAuth Application you created in Step 1.

Step 3: Connect

Each user must authenticate individually before agents can use the MCP tools on their behalf.

Admins can verify the configuration works from Project Settings > Apps: find the installed app and click Connect next to the OAuth-enabled MCP collection to complete the OAuth consent flow.

End users connect from the new agent form in the Agent Runner interface before starting the agent. The form displays connect actions for any OAuth-enabled MCP collections that require authentication.

Tokens are stored securely and refreshed automatically. If a refresh token expires or is revoked, the user will need to reconnect.

Complete Example

An app manifest with multiple MCP servers:

{
  "name": "my-sales-app",
  "visibility": "private",
  "title": "Sales Integration",
  "description": "Connect sales tools to Vertesia agents",
  "publisher": "My Organization",
  "status": "stable",
  "endpoint": "https://my-app.example.com/api/vertesia",
  "tool_collections": [
    {
      "type": "mcp",
      "url": "https://mcp.my-crm-provider.com",
      "name": "My CRM",
      "description": "CRM tools for contacts, deals, and companies",
      "namespace": "crm",
      "auth": "oauth",
      "oauth_app": "my-crm-oauth"
    },
    {
      "type": "mcp",
      "url": "https://mcp.internal.example.com/v1",
      "name": "Internal Tools",
      "description": "Internal MCP tools",
      "namespace": "internal"
    }
  ]
}

This example configures:

An endpoint for Vertesia SDK tools (discovered automatically)
An MCP server with OAuth authentication
An MCP server without authentication