Articles in this section

Connect a Celigo MCP server to Microsoft Copilot studio

Michelle Welch
Updated

You can connect a Celigo MCP server to a Microsoft Copilot Studio agent as a tool. Copilot Studio reads the tools the MCP server exposes, shows each tool's inputs, and lets the agent call those tools during a conversation. You add the server with Copilot Studio's built-in wizard — no OpenAPI file or Power Apps custom connector setup is needed.

This article is for admins and builders who set up a Copilot Studio agent and for end users who need to know how the agent connects to Celigo. Copilot Studio supports only the streamable HTTP transport for MCP servers, and Celigo MCP servers use streamable HTTP, so no transport configuration is needed. If you're an admin setting up the Celigo side, see Configure MCP server authentication. If you're connecting from Claude, Cursor, or another MCP client, see Connect the Celigo MCP server to Claude and Cursor.

This article covers the prerequisites, how to find your MCP server URL, which authentication method to choose, how to add the server and create its connection in Copilot Studio, how to test the tools, how to design Celigo Tools so Copilot Studio can call them, and common troubleshooting.

Prerequisites

  • You need access to Copilot Studio with permission to create agents and add tools. Copilot Studio creates a Power Platform custom connector for each MCP server you add, so any data policy that governs Power Platform connectors in your tenant also governs the MCP server and its tools.
  • You need the MCP server URL. Your Celigo admin provides it — see Find your MCP server URL.
  • You need a credential for the server. Either an API token that your Celigo admin creates for the MCP server (recommended today) or, for OAuth, a Celigo end-user record with access to the server. Workspace access alone doesn't grant MCP access — see Connect to a Celigo MCP server as an end user.
  • Your browser must allow pop-ups from Copilot Studio if you use OAuth. The sign-in consent opens in a pop-up window.
  • Create the agent as a standard agent. When you select New agent, choose the Agent, Standard type (standard orchestration). For Copilot credit usage information, see the Limits section in Add an MCP server to your agent as a tool.

Find your MCP server URL

End users get the MCP server URL from their admin — end users can't sign in to integrator.io to look it up.

Admins can find it in integrator.io:

  1. Go to AI studio > MCP servers and select the MCP server.
  2. On the Configuration tab, find the Relative URI field.

  3. The full MCP server URL is the base URL plus the relative URI. For example:

    https://api.integrator.io/mcp/your-account-alias/your-server-name

Copy the full URL. Copilot Studio requires the complete server path — the Server URL field won't let you continue with only the base URL.

Choose an authentication method

Copilot Studio offers three authentication options for an MCP server: None, API key, and OAuth 2.0. Celigo MCP servers always require authentication, so None doesn't work.

Method Use it when
API key with a Celigo API token You want the fastest setup, or the agent runs as a service rather than as individual people. The agent sends the same token for every user.
OAuth 2.0 > Dynamic discovery You want each person who uses the agent to sign in with their own Celigo end-user credentials, so their access follows what the admin granted them.
OAuth 2.0 > Manual Advanced only. You've registered an OAuth client with Celigo yourself. See Advanced: manual OAuth.

API key with a Celigo API token

Ask your Celigo admin for an API token for the MCP server. Admins create one in integrator.io: go to AI studio > MCP servers, select the MCP server, open the Access tab, select API tokens, then select Create token. Copy the token value when it's shown. Tokens can auto purge after a set period or never, and admins can revoke them at any time. Treat the token like a password — anyone who has it can use the server with the token's access.

In Copilot Studio you enter the header name (Authorization) when you add the server, and the token value later, when you create the connection. The value must include the Bearer prefix — see Create the connection.

If you build or edit the connector in Power Apps instead of using the wizard, open the connector's Security tab and set Authentication type to API Key, Parameter label to Authorization, Parameter name to Authorization, and Parameter location to Header. The Parameter name is the HTTP header name that's sent to the MCP server; the Parameter label is the field name people see when they create the connection. The connection value is still Bearer, a space, and the token.

OAuth 2.0 with Dynamic discovery

With Dynamic discovery, Copilot Studio reads the MCP server's OAuth metadata, registers itself as a client with Celigo, and opens the Celigo sign-in page when you create the connection. You sign in with your Celigo end-user credentials, or through your company's identity provider if your admin has configured one for your email domain. The account that signs in must have access to the MCP server.

No client ID, client secret, or callback registration is needed on the Celigo side. Copilot Studio handles registration for you.

Advanced: manual OAuth

Use Manual only if you have registered an OAuth client with Celigo yourself. Celigo has no UI for registering OAuth clients — clients are registered through the standard OAuth dynamic client registration endpoint, POST https://integrator.io/oidc/reg, which is an admin-level, advanced path. If you go this route, the wizard values are:

  • Authorization URL — https://integrator.io/oidc/auth
  • Token URL template — https://integrator.io/oidc/global/token
  • Refresh URL — https://integrator.io/oidc/global/token
  • Scopes — mcp:read mcp:write offline_access

After you select Create, Copilot Studio shows a Redirect URL of the form https://global.consent.azure-apim.net/redirect/<connector-name>. Register that exact URL as a redirect URI on your OAuth client before you create the connection.

Add the MCP server to your agent

  1. Follow the instructions in the Microsoft Copilot Studio help article Connect your agent to an existing MCP server to configure basic server details.
    • Server name — A short name for the server. Use letters, digits, spaces, hyphens, or underscores, start with a letter or digit, and stay within 30 characters. Parentheses and other punctuation are rejected.
    • Server description — One or two sentences on what the server does. The agent's orchestrator uses this description to decide when to call the server, so be specific: "Search Celigo Help Center articles and Zendesk support tickets" works better than "Celigo tools".
    • Server URL — The full MCP server URL from your admin, for example https://api.integrator.io/mcp/your-account-alias/your-server-name.
    • Authentication — Select API key or OAuth 2.0.
  2. Complete the authentication fields:
    • For API key: Select Header and enter Authorization as the name. 
    • For OAuth 2.0: Select Dynamic discovery.
  3. Follow the steps to Create a new connection and add the MCP server to your agent. 
    1. For API key, enter Bearer, a space, and then the API token — for example Bearer abc123…. Copilot Studio doesn't add the Bearer prefix for you. A raw token is sent as-is and Celigo rejects it as unauthorized. For OAuth 2.0, there's no credential field. Note: The Bearer prefix is the most common setup mistake. If the tool list shows an unauthorized error right after you create an API-key connection, open the connection, replace the value with Bearer followed by a space and the token, and try again.
    2. Follow the on-screen instructions to create your connection and finish adding the server to your agent.
  4. Test your agent. If the agent replies with Let’s get you connected first, the connection isn’t bound to your test session yet. Ensure your connection shows as Connected, then return to the Test pane and send the prompt again.

Design your tools for Copilot Studio

Copilot Studio can only fill in the inputs it can see. It reads each tool's input schema from the MCP server and shows every top-level property with its description, type, and required flag — and that per-input flag is the only rule it can see. If none of a Tool's inputs is required, Copilot Studio can call the Tool with no arguments at all, and if the Tool needed one, Celigo rejects the call with Invalid params. Follow these guidelines when you build the Celigo Tools you expose on the MCP server.

  • Define every input explicitly. Give each input a name, a description, and a simple single type — string, number, or boolean. Copilot Studio shows these as String, Number, and Boolean, and array inputs as Table.
  • Mark the inputs the Tool can't run without as required. Copilot Studio fills required inputs — the agent infers them from the conversation or prompts the user for them — and may leave optional inputs empty. A Tool whose inputs are all optional can be called with no arguments. In the Tool builder every new input is optional by default, so set the flag yourself — see Mark an input as required in the Tool builder.
  • Don't express "at least one of these inputs" with a root-level anyOf, oneOf, or allOf. Copilot Studio shows only each input's own required flag, so it can't see a rule that spans several inputs. Every input in such a schema looks optional to it, the agent can send none of them, and the call fails schema validation on the Celigo server with Invalid params. Marking one of the identifier inputs required doesn't fix it — the agent then has to supply that key even when the user gave a different identifier. Use one of these patterns instead:
    • Pattern A, a discriminator. Two required string inputs: searchBy, whose description lists the identifiers the Tool accepts (for example email, customer_id, or company_name), and searchValue, the value to look up. You can add an enum to searchBy — Celigo enforces it before the Tool runs — but Copilot Studio treats enums as plain strings, so keep the list in the description.

    • Pattern B, one Tool per key. Create one Tool per identifier, each with a single required input: lookup_customer_by_email with only email, lookup_customer_by_id with only customer_id, and so on. In Celigo's stored form, the Tool input for lookup_customer_by_email is:

      {
  "name": "Input",
  "schema": {
    "type": "object",
    "properties": {
      "email": { "type": "string", "description": "Email address of the customer to look up" }
    },
    "required": ["email"]
  },
  "mockInput": { "email": "jane@example.com" }
}
  • Prefer flat scalar inputs. Nested objects and schema references ($ref) aren't supported — Copilot Studio filters out tools whose inputs use references. An input whose type is an array of types (for example ["string", "null"]) truncates the schema; use one type. Enumerations are treated as plain strings, so list the allowed values in the input's description instead.
  • Write descriptions the orchestrator can act on. Copilot Studio decides when to call a tool from the tool's description and the server description you entered. Say what the tool does and what it returns.
  • Use MCP-safe tool names. Use letters, digits, underscores, hyphens, and dots — no spaces. For example, name a Tool lookup_netsuite_customers rather than Lookup NetSuite Customers. Copilot Studio passes the name through verbatim and uses it as the identifier the agent calls.
  • Refresh the tool list after you change a Tool. Copilot Studio reads tools when you add the server. After you rename a Tool or change its inputs in Celigo, open the tool in Copilot Studio and refresh the Tools section, or remove the MCP server from the agent and add it again.

Mark an input as required in the Tool builder

  1. In integrator.io, open the Tool and select the Tool input step.
  2. Under Create schema, select Manual. Each input is listed under the Create record { } row with a type dropdown, its name, and a gear icon at the right end of the row.
  3. Select the gear icon on the input's row to open the Additional settings panel.
  4. Select the Required checkbox. Consider clearing the Allow null checkbox as well, so the agent can't satisfy the input with a null value.
  5. Select Save in the Additional settings panel, then select Save at the bottom of the Tool input step.
  6. In Copilot Studio, refresh the tool list or remove and re-add the MCP server so it reads the new schema.

If the Tool's schema is in JSON mode and uses anyOf, oneOf, or allOf, either rewrite it in JSON mode with a top-level required list and remove those keywords, or switch to Manual — integrator.io asks you to confirm, because switching removes JSON-only keywords such as anyOf — and then mark the input required as in steps 3 to 5. Manual mode supports basic types, validations, and the required flag; it can't express anyOf, oneOf, or allOf.

Troubleshoot Copilot Studio connections

Unauthorized error right after you create an API-key connection

The token value is missing the Bearer prefix. Copilot Studio sends the header value exactly as you entered it. Open the connection and set the value to Bearer, a space, and the token. If the token itself is wrong, revoked, or auto purged, ask your admin for a new one.

If you built or edited the connector in Power Apps, also open its Security tab and confirm that Parameter name is Authorization and Parameter location is Header. A different parameter name sends the token under the wrong header, and Celigo rejects the request as unauthorized. See API key with a Celigo API token.

The full message is "The connection consent pop-up window has been blocked by the browser. Please allow pop-ups in your browser and try again." OAuth sign-in opens in a pop-up window. Allow pop-ups for Copilot Studio in your browser, then create the connection again. Embedded or restricted browsers that block window.open can't complete OAuth sign-in — use a standard desktop browser.

The connection for this tool is no longer valid

The tool's detail page shows "The connection for this tool is no longer valid (it may have been deleted or its authorization revoked). Create a new connection and reselect it for this tool," and no tools are listed. The connection exists but never finished authenticating — typically because the sign-in pop-up was closed or blocked — or its authorization was revoked. View details shows Celigo's response, Authorization required. See WWW-Authenticate header. Create a new connection, complete the sign-in, and select the new connection for the tool.

Something went wrong when you select Create

The wizard shows only "Something went wrong. Please try again." The Server name doesn't meet Copilot Studio's naming rules, which the wizard doesn't spell out. Names must use letters, digits, spaces, hyphens, or underscores, start with a letter or digit, and be 30 characters or fewer. Parentheses fail — Celigo Zendesk (manual OAuth) is rejected, Celigo Zendesk manual OAuth is accepted.

Uses Copilot Credits, or the Test pane won't respond

Your agent type is metered by Copilot Credits and the tenant has none. Create a new agent and choose Agent, Standard when you select New agent. Standard agents use standard orchestration and consume no credits for users with a Copilot license. Then add the MCP server to that agent.

Invalid params on a tool call

The agent called the Tool without the input it needs — usually with no arguments at all. The common causes are that every input is optional, so Copilot Studio wasn't required to fill any of them; that the schema expresses "at least one of these inputs" with a root-level anyOf, oneOf, or allOf, which Copilot Studio can't see; or that the inputs are in a form Copilot Studio can't read (nested objects, $ref, or multi-type arrays). In integrator.io, open the Tool and mark the input it can't run without as required (Tool input step > Create schema > gear icon > Additional settings > Required), or restructure the inputs as a required searchBy and searchValue pair or as one Tool per lookup key; define the remaining inputs explicitly with descriptions and simple types, then refresh the tool list in Copilot Studio or remove and re-add the MCP server. See Mark an input as required in the Tool builder and the input patterns in Design your tools for Copilot Studio.

Tools are missing, stale, or the agent won't call them

  • Check the Enabled toggle for the MCP server on the Tools page and the per-tool toggles on its detail page.
  • Start a new test session — an agent conversation only sees the tools that existed when it began.
  • If you changed a Tool in Celigo, remove and re-add the MCP server so Copilot Studio re-reads the tool list.
  • If the agent answers without calling the tool, name the tool in your prompt and check that the tool and server descriptions say what the tool does.

Authorization error after you sign in with OAuth

Signing in proves who you are; it doesn't grant access. Your end-user record doesn't have access to this MCP server. Ask your Celigo admin to add you to a group with access to it or to grant you direct access. See Troubleshoot end-user MCP server access.

Method Not Allowed in the Power Apps custom connector Test tab

Copilot Studio creates a custom connector for each MCP server. If you open that connector in Power Apps and use its Test tab, the request it sends isn't an MCP request, and Celigo answers Method Not Allowed. This doesn't indicate a problem with the server. Test from the agent's Test your agent pane instead.