Articles in this section

Create an MCP connection

Create a connection to a remote Model Context Protocol (MCP) server by selecting a vendor's server from the application list or by entering the server's URL. A listed server comes with its URL and authentication settings filled in, so you enter only what the vendor requires. For a server that isn't listed, enter its URL, and Celigo reads the authentication settings the server publishes and pre-selects the authentication method. For vendors that accept Client ID Metadata Documents, you connect with a name, the URL, and a sign-in, with no OAuth 2.0 client (iClient), client ID, client secret, or scopes. For other OAuth 2.0 servers, a new iClient opens prefilled, so you enter only the client ID and secret of an app you registered with the vendor.

Prerequisites: Complete the items that apply to your path.

  • MCP server URL - To enter a server URL, an absolute https URL for the MCP server.
  • Automatic - A vendor whose authorization server accepts Client ID Metadata Documents and supports Proof Key for Code Exchange (PKCE) with SHA-256. If Automatic is disabled on the form, the vendor doesn't meet these conditions. See When Automatic isn't available. If the vendor restricts which apps can connect, an administrator may need to allow Celigo first. Celigo's client ID is the URL of its Client ID Metadata Document on your region's integrator.io host.
  • Pre-registered client - An app registered with the vendor, with its client ID and client secret. The app must allow the Redirect URL shown on the iClient form.

Connect to a predefined MCP server

Celigo provides predefined connections for supported vendor MCP servers, such as Asana, Atlassian, GitHub, and Linear. Select a server to use its preconfigured URL and authentication settings.

  1. Go to Resources, and then select Connections.
  2. Select + Create connection.
  3. In Application, search for the vendor, and then select it under MCP servers. 

    create mcp connection.png

    After you select a server, application reads MCP, and the connections list shows the vendor's name.

  4. Enter a name in Name your connection.
  5. (Optional) Select Connection guide to see the vendor's steps to complete before you authorize.
    connection guide.png
  6. Complete the authentication settings shown for the selected server. A server such as Linear shows none, so select Save & authorize, and Celigo registers itself with the server. For a server such as Asana, GitHub, Google, or HubSpot, Client registration shows both choices, with Pre-registered client selected:
    • Pre-registered client - In OAuth 2.0 client, select an iClient or select + to create one with the client ID and secret of an app you registered with the vendor, and then select Save & authorize. See Connect with a pre-registered client.
    • Automatic - Select Automatic, and then select Save & authorize. For the sign-in and approval, see Connect with Automatic registration.
  7. To use another authentication type, such as Token or Custom, select MCP. The MCP view lists every authentication type Celigo offers, whether or not the vendor's definition declares it, and even when Simple shows only one. For the settings, see Create an MCP connection from an AI agent.

Note: A server you select under MCP servers creates a connection to the vendor's MCP server, not to a Celigo MCP server. The same vendor name under Connectors uses the application's standard connector.

If a predefined MCP server is removed from the application list, you can still open and rename connections you saved for it. You can't switch their authentication mode, and you can't create a new connection to that vendor.

View MCP server settings

The Simple view shows the fields required to connect to the selected vendor. Select MCP to view the server URL and additional authentication settings. You can switch between Simple and MCP without losing the values you've entered while the form stays open. If you close a new connection after switching to MCP, the form shows "You've got unsaved changes."

mcp server settings view.png

How URL-first setup works

When you enter a valid https URL in MCP URI on a new MCP connection and stop typing for about a second, Celigo checks the server's published authentication settings. MCP URI shows "Checking the server's authentication settings" while the check runs, and the form stays usable. When the server publishes OAuth 2.0 settings, Configure authentication fills in:

  • Auth type is set to OAuth 2.0.
  • Client registration is set to Automatic when the server can support it, and to Pre-registered client otherwise.
  • Scope is prefilled with the scopes the server publishes, on the Pre-registered client path only.

If the check fails, the form shows no message and nothing is pre-selected. If the server publishes no OAuth 2.0 settings, Auth type stays empty. When you select OAuth 2.0, Automatic is disabled with "This server doesn't publish OAuth 2.0 settings." and Pre-registered client is selected.

Change the URL on a new connection

Each time you change the URL to a different valid https URL and stop typing for about a second, Celigo checks again, including when you return to an earlier URL. The new result refreshes only Auth type, Client registration, and Scope, and only where the earlier check set the current value. A corrected URL no longer keeps the first server's settings, and values you entered yourself are never overwritten. A failed check changes nothing and shows nothing.

Change the URL or registration on a saved connection

Opening a saved connection runs no check. Two changes do, before anything is saved, and the check changes nothing on the connection. Auth type, Scope, and the selected OAuth 2.0 client never change. Client registration shows "Checking the server's authentication settings" while the check runs.

  • Select Automatic. On a connection saved as Pre-registered client or with no saved mode, Save & authorize waits for the check. If the server supports Automatic, the selection stays. Otherwise, the selection returns to Pre-registered client with "Switched back to Pre-registered client." followed by the reason, your saved OAuth 2.0 client and Scope are restored, and Automatic stays disabled with its reason until you change the URL. If the check can't finish, the selection returns with "Couldn't check whether this server supports automatic registration. Try again." and Automatic stays available.
  • Change the URL. The check changes only whether Automatic is available. A connection saved as Automatic keeps that selection when the new server can't support it, and Client registration shows the reason followed by "Switch to a pre-registered client to continue." Returning to the saved URL drops the check's result and leaves your saved selection as it was.

Selecting Automatic right after a URL check confirmed support applies at once. Token and Custom connections run no check, and closing the form discards a check that is running.

Choose between Automatic and Pre-registered client

Client registration decides how Celigo identifies itself to the server's authorization server. It appears under Auth type set to OAuth 2.0 on MCP connections only.

  Automatic Pre-registered client
How Celigo identifies itself With its Client ID Metadata Document on your region's integrator.io host. Its URL is the client ID. With an iClient that holds the client ID and secret of your registered app.
What you enter A name and the URL. A name, the URL, and the app's client ID and secret.
Scopes Chosen at each authorization. There is no Scope setting. Prefilled in Scope and editable.

Use Automatic whenever the server supports it. Use Pre-registered client when the vendor requires an app registered in your own tenant, when you need to set scopes by hand, or when the vendor rejects Celigo's client. Many vendors don't yet accept Client ID Metadata Documents and need Pre-registered client.

Create the connection

  1. Go to Resources, and then select Connections.
  2. Select + Create connection, and then select Remote MCP server under MCP servers to enter a server URL manually. 

    new remote MCP server.png

  3. In General, enter a Name.
  4. In Application details, enter the server's URL in MCP URI, and wait for the check to finish. (Optional) Add any HTTP headers the server requires. See Create an MCP connection from an AI agent.
  5. Continue with the path that matches Client registration.

Connect with Automatic registration

  1. Confirm that Auth type is OAuth 2.0 and Client registration is Automatic.
  2. Select Save & authorize. Celigo opens the vendor's sign-in in a new window. The consent screen names Celigo. 

    client authorization.png

  3. Sign in and approve.

The window and the form close, and the connection appears as online. If the consent screen shows no permissions, the server published no scopes, and Celigo requested none. After authorization, the connection shows which registration method it used. If an error banner appears instead, see Troubleshoot authorization failures.

Note: Some vendors require the account you sign in with to belong to a workspace. If it doesn't, the connection doesn't appear as online and can't load the server's tools. Join a workspace in the vendor's application, and then check the connection.

Connect with a pre-registered client

Use this path when Client registration is Pre-registered client. To use your own app on a server that supports Automatic, select Pre-registered client first.

  1. In Configure OAuth 2.0, next to OAuth 2.0 client, select +. The Create iClient form opens with Grant type, Authorization URL, Access token URL, Revoke token URL (when the server publishes one), Valid domain names, and Send token via already filled in.
  2. Enter a Name, Client ID, and Client secret. Valid domain names lists the server's hosts as registrable domains, separated by commas, and Send token via is set to HTTP header, Authorization, and Bearer. For the other settings, see Create an OAuth 2.0 iClient resource.
  3. Save the client, and then review Scope. After a check or an authorization failure, Scope holds the scopes the server published.
  4. Select Save & authorize, sign in to the vendor, and approve.

To use an iClient you already have, select it in OAuth 2.0 client instead. Celigo never changes an existing iClient, so confirm that its endpoints match this server.

When Automatic isn't available

Automatic is disabled, with its reason shown when you point to or focus it, when the authorization server doesn't accept Client ID Metadata Documents, doesn't support Proof Key for Code Exchange (PKCE) with SHA-256, or publishes no OAuth 2.0 settings. Client registration moves to Pre-registered client with the discovered values prefilled. Continue with Connect with a pre-registered client. A failed check doesn't disable Automatic, because a failure says nothing about the server.

Re-authorize a connection

When a vendor moves an endpoint or declines to refresh the connection's tokens, the connection goes offline. Open the connection and select Save & authorize. On Automatic, authorizing checks the server again and picks up the new endpoints. On Pre-registered client, update the iClient's URLs first if the vendor changed them.

Changing Client registration on a saved connection also requires authorizing again. When your selection differs from the saved one, Client registration shows "Changing how Celigo registers with this server requires you to authorize again." Celigo never changes Client registration on its own.

Limits

  • No Dynamic Client Registration. A vendor that offers only Dynamic Client Registration takes the Pre-registered client path with an app you register by hand. Celigo makes no dynamic registration request.
  • No manual scopes on Automatic. To set scopes by hand, use Pre-registered client.
  • A pre-registered client needs a client secret. A vendor's public-client choice, which issues no secret, can't be used.
  • MCP connections only. Generic HTTP connections keep their existing OAuth 2.0 behavior, and the registration failure details in the status banner appear for MCP connections only.
  • Existing connections are unchanged. An OAuth 2.0 MCP connection that uses an iClient shows Pre-registered client.
  • Automatic depends on your region's Client ID Metadata Document. If it isn't available, Automatic can't be used, and authorizing fails with the first message in the troubleshooting table.
  • Checks run only on the changes described. Opening a saved connection runs no check, and a check never changes Auth type, Scope, or the selected OAuth 2.0 client. A Pre-registered client connection whose URL moves to a different authorization server keeps its iClient and Scope until you change them, and a stale iClient surfaces when you authorize.
  • The authorization server decides. A vendor can reject Celigo's client at sign-in or grant fewer scopes than requested, and no check can predict it. Celigo doesn't retry a different method on its own.
  • Predefined MCP servers. You can't change the vendor after you save a connection. Create a new connection to use a different server.

Troubleshoot authorization failures

When registration or authorization fails on an MCP connection, a status banner at the top of the form shows the full message and, when the vendor answered, "Vendor response: error — description". View log opens the API calls the failure made, beside the form. Before sign-in, it lists the request to the MCP server, the protected resource metadata request, and the authorization server metadata request. After sign-in, it lists the callback and the token exchange. The banner has no action that edits the form. To switch methods, select Pre-registered client in Client registration, which also fills Scope with the scopes the server published. For the general procedure, see Create a connection to an application.

Message Cause Resolution
"This server's authorization server doesn't support automatic client registration. Switch to a pre-registered client." The server doesn't accept Client ID Metadata Documents, or your region's document isn't available. Change Client registration to Pre-registered client.
"This server's authorization server doesn't support PKCE with SHA-256, which automatic client registration requires. Switch to Pre-registered client." The server doesn't support PKCE with SHA-256. Change Client registration to Pre-registered client.
"The authorization server rejected Celigo's client. Switch to a pre-registered client." For example, "Vendor response: invalid_client — Client metadata document host is not in the trusted domain list" The vendor rejected Celigo's client, usually under a domain trust policy. Ask the vendor's administrator to allow Celigo, or change Client registration to Pre-registered client.
"The authorization server rejected the requested scopes. Switch to Pre-registered client to set the scopes manually." For example, "Vendor response: invalid_scope — The requested scope is invalid: read write" The vendor refused the scopes Celigo selected, or refused an authorization with no scope. Change Client registration to Pre-registered client and set Scope by hand.
"Celigo couldn't read authentication settings from this server. Check the URL, or configure authentication manually." The server's metadata was unreachable, or the URL points at a private address. Check that the URL is an absolute https URL for the MCP endpoint, or configure authentication manually.
"The server took too long to return its authentication settings. Try again, or configure authentication manually." The check didn't finish in time. Try again, or configure authentication manually.
"The server returned authentication settings that Celigo couldn't use. Check the URL, or configure authentication manually." The metadata was malformed or didn't match the URL. Check the URL against the vendor's documentation.
"Automatic client registration is currently turned off. Try again later." Automatic registration is turned off for your region. No call was made, so there is no View log. Try again later, or use Pre-registered client.
"Authorization could not be completed because no callback was received. Please try again." You closed the vendor's window, or the vendor showed its own error page. There is no View log. Select Save & authorize again. If the vendor reports a client or redirect URL error, its administrator may need to allow Celigo.
"Unable to retrieve the oAuth auth-code from query string." You denied consent on the vendor's page. Select Save & authorize again and approve.
"Unable to connect to the MCP server. Please check your connection settings and try again." with View log Sign-in succeeded, but the connection test failed, for example because the path in the URL is wrong. The connection is saved and marked offline. Fix the URL, and then test or authorize again.

A tool call fails because the connection is missing permissions

When a server answers a call with 403 insufficient_scope, the call fails with an error that names the missing permissions and says to re-authorize the connection in integrator.io. Through a Celigo MCP server's proxy, the end user's AI client receives that message. The connection stays online.

  1. Open the connection and select Save & authorize.
  2. Approve the vendor's consent screen. Celigo requests the scopes it was granted before, plus the ones the server asked for.

If the authorization server keeps withholding the scopes, Celigo stops asking after a limited number of attempts. Change Client registration to Pre-registered client and add the named scopes to Scope.

The connection is offline

An offline Automatic connection shows "This connection is offline. Re-authorize to bring it back online." Select Save & authorize. An offline Pre-registered client connection shows "This connection is currently offline. Re-enter your credentials to bring it back online." and may need the iClient's secret or URLs updated first. See Re-authorize a connection.