---
title: "Vertesia MCP Connector"
source: "https://docs.vertesiahq.com/integrations/mcp"
markdown: "https://docs.vertesiahq.com/llms/integrations/mcp.md"
---

# 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:

| Region | MCP server URL |
| --- | --- |
| US1 | `https://mcp.us1.vertesia.io/mcp` |
| EU1 | `https://mcp.eu1.vertesia.io/mcp` |

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)](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/),
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:

| Client | Callback or redirect URI |
| --- | --- |
| Claude.ai | `https://claude.ai/api/mcp/auth_callback` |
| Claude Desktop | `http://127.0.0.1:3334/callback` |
| ChatGPT | Use the exact callback URL displayed while creating the plugin |

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](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp).

## 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.

```bash
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:

```bash
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:

```bash
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](https://developers.openai.com/codex/mcp).

## 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:

| Region | Identity-provider redirect URI |
| --- | --- |
| US1 | `https://cloud.us1.vertesia.io/__/auth/handler` |
| EU1 | `https://cloud.eu1.vertesia.io/__/auth/handler` |

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](https://vertesiahq.com/privacy) and [Terms of Service](https://vertesiahq.com/terms).

## 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](mailto:support@vertesiahq.com).