Vertesia MCP Connector

The Vertesia MCP connector gives supported AI clients access to the tools and resources in your Vertesia project. Use it to inspect and manage agents, interactions, prompts, processes, documents, views, project access, event automation, and agent runs.

Choose your Vertesia region

Use the endpoint for the region that hosts your Vertesia account and project:

You can find your assigned region in Vertesia Studio under User menu > Environment. A client configured with one region cannot access an account or project hosted in another region.

The marketplace connector currently uses US1. Direct connections from Claude Code, Codex, the ChatGPT desktop app, and other MCP clients can use either regional endpoint.

Requirements

Before connecting, you need:

• a Vertesia user identity with access to an account and project in the selected region;
• permission to use the resources and operations you intend to invoke; and
• an MCP client that supports remote Streamable HTTP servers and browser-based OAuth.

The connector can only access resources available to the signed-in Vertesia user. Project permissions and access controls continue to apply to every tool call.

OAuth client setup

Vertesia supports Client ID Metadata Documents (CIMD), which lets compatible clients identify themselves without a separately issued client ID or secret. Vertesia does not support OAuth Dynamic Client Registration (DCR).

Use CIMD when the client supports it. Current Claude Code discovers CIMD automatically. If a client requires a pre-registered OAuth client instead, create one in Vertesia Studio under Settings > Applications > OAuth Clients:

1. Enter a recognizable client name.
2. Add the exact callback or redirect URI supplied by the MCP client.
3. Optionally restrict the OAuth client to specific scopes or a specific Vertesia project.
4. Copy the client ID into the MCP client's advanced OAuth settings.

Only create a client secret when the MCP client explicitly requires one. Public clients using PKCE normally do not need a secret. Never paste an OAuth client secret, Vertesia API key, or access token into a chat.

Common callback URIs are:

Callback URIs must match exactly, including the scheme, host, port, path, and trailing slash if one is shown.

Connect from Claude.ai

If Vertesia is available in the Connectors Directory, select it and choose Connect. For a custom connection:

1. Open Customize > Connectors.
2. Select + > Add custom connector and enter the MCP server URL for your Vertesia region.
3. If requested, open Advanced settings and enter the client ID for an OAuth client registered with the Claude.ai callback URI shown above.
4. Add the connector, choose Connect, and complete Vertesia sign-in in the browser.
5. Select the Vertesia account and project, then review and approve the requested access.

Workspace owners may need to configure the connector before other members can connect it. The exact controls depend on the Claude plan and workspace policy. See Anthropic's custom connector instructions.

Connect from Claude Code

Add Vertesia as a user-scoped remote HTTP server so it is available in every project. Substitute the EU1 endpoint if your Vertesia project is hosted in EU1.

claude mcp add --transport http --scope user vertesia https://mcp.us1.vertesia.io/mcp

Then start Claude Code and run /mcp, or authenticate directly from the shell:

claude mcp login vertesia

Complete the browser sign-in, select an account and project, and approve the requested scopes. Use claude mcp list to verify that Vertesia is connected. Claude Code discovers Vertesia's CIMD support automatically, so a registered OAuth client and fixed callback port are not normally required.

Connect from ChatGPT and Codex

ChatGPT web

Install the published Vertesia plugin when it is available in the Plugins directory. During development or private testing, create a plugin using the MCP server URL for your region and select CIMD in the advanced OAuth settings.

If CIMD is unavailable in your ChatGPT workspace, create a Vertesia OAuth client using the exact callback URL shown by ChatGPT, then enter its client ID in the plugin's OAuth settings. After connecting, complete Vertesia sign-in and select the account and project to authorize. Workspace administrators can control whether custom or published plugins are available.

ChatGPT desktop app, Codex CLI, and Codex IDE extension

These clients share the same local MCP configuration. In the ChatGPT desktop app or Codex IDE extension, open Settings > MCP servers, add a Streamable HTTP server using the regional Vertesia URL, save it, and restart the client. Select Authenticate when prompted.

To configure the same server from the command line:

codex mcp add vertesia --url https://mcp.us1.vertesia.io/mcp
codex mcp login vertesia

Use codex mcp list or /mcp in the Codex terminal interface to verify the connection. For more detail, see the Codex MCP documentation.

Authentication and authorization

Vertesia delegates user authentication to Firebase and the OpenID identity provider configured for your account. The MCP authorization flow does not ask you to create or copy a Vertesia password.

The selected account and project determine the connector context. Within that context:

• read tools can inspect only data visible to your identity;
• write tools require the permissions associated with the requested operation;
• destructive operations are identified in tool metadata so the host can request confirmation; and
• disconnecting the connector prevents the client from making additional calls with that authorization.

Authorization does not grant access to other Vertesia projects or bypass project-level access controls.

Enterprise SSO configuration

If your organization uses an external identity provider, its allowed redirect URIs must include the Firebase auth handler for every Vertesia region your users access:

Registering only https://cloud.vertesia.io is not sufficient. This configuration belongs in the enterprise identity provider and is separate from the MCP client's OAuth callback URI.

Capabilities

The connector exposes the Vertesia Studio MCP tool catalog except for project-wide configuration updates. Capabilities include:

• listing, inspecting, creating, updating, publishing, and deleting prompts and interactions;
• running interactions and diagnosing agent execution;
• designing, validating, starting, and monitoring processes;
• searching, reading, creating, and updating project documents;
• managing views, environments, members, roles, and access controls;
• configuring event subscriptions and inbound event channels; and
• inspecting workflow runs, child runs, traces, and artifacts.

The connector also exposes focused guides for multi-step Vertesia workflows. MCP clients may present these guides as skills or as learn_* tools. The tools available to the client may evolve as Vertesia adds capabilities, while the permissions of the signed-in user remain authoritative.

Safety and data handling

• Start with read-only requests when exploring a project.
• Review the exact target before approving an update, publication, access-control change, or deletion.
• Use a non-production project when testing write or destructive workflows.
• Do not ask the connector to return secrets, authentication tokens, or data you are not authorized to access.
• Treat signed download or upload URLs as temporary credentials: do not paste them into chat or share them with another user.

Connector requests are processed in the region of the selected MCP endpoint. For details about data handling, see the Vertesia Privacy Policy and Terms of Service.

Troubleshooting

Sign-in does not complete

Allow pop-ups and redirects for the AI client and Vertesia authentication pages, then retry the connection. Make sure you use an identity that has already been invited to the intended Vertesia account.

If a registered OAuth client is in use, verify that its callback URI exactly matches the URI sent by the MCP client. For enterprise SSO, confirm that the identity provider allows the regional __/auth/handler URI listed above.

The expected account, project, or resource is missing

Confirm that the MCP server URL uses the region that hosts the account. Then confirm that you selected the correct account and project during authorization. The connector cannot see resources outside that project or resources hidden by its access-control rules.

The client reports unsupported OAuth registration

Use CIMD when the client supports it. If the client only supports pre-registered OAuth clients, create one in Vertesia Studio and provide the exact callback URI and client ID as described above. DCR is not supported.

A write operation is denied

Your Vertesia role may not include the required permission, or the AI client may still require confirmation. Ask a Vertesia project administrator to verify your role; do not share credentials or tokens to work around the denial.

The connector must be removed

Disconnect Vertesia from the AI client's connector or app settings. If access must be revoked centrally, contact your Vertesia administrator.

For additional help, contact support@vertesiahq.com.