Add a Model Context Protocol (MCP) server to your agent as a tool (preview)

[This article is prerelease documentation and is subject to change.]

Model Context Protocol (MCP) is a standard for exposing tools to an agent. When you add an MCP server to your agent, every tool the server exposes becomes available for the agent to invoke during a conversation.

Note

This article reflects the new experiences for creating agents and workflows in Microsoft Copilot Studio. The new agent experience is currently available as a production-ready preview. Learn about the two agent experiences in Classic vs. new agent experience. The new workflows experience is in public preview. Learn about the two workflows experiences in Workflows overview.

  • Public preview features aren't meant for production use and might have restricted functionality.
  • Production-ready and public previews are subject to supplemental terms of use.
  • Some capabilities available in the classic experience aren't yet available in the new experience.
  • Agents and workflows created in the new experience can't be converted to the classic experience.

Use this how-to when you want to add an MCP server to an agent in the new experience. For an overview of tool types in the new experience, see Available tools for agents.

Prerequisites

  • An agent created in the new experience. See Create an agent.
  • The URL of an MCP server that's reachable from Copilot Studio. If you don't have one yet, see Create a new Model Context Protocol (MCP) server.
  • Any credentials required by the server (for example, an API key or a client ID and secret for a supported authentication scheme).

Add an MCP server from the Build tab

  1. Sign in to Copilot Studio and open your agent.

  2. In the agent navigation bar, select the Build tab.

  3. In the components panel on the right, select Tools.

  4. In the Add a tool dialog, select Add next to the search bar, and then select Model Context Protocol (MCP).

  5. On the Add MCP server page, enter the following details:

    • Name: a short, descriptive name that helps the agent decide when to use this server's tools. This name is what the agent sees.
    • Description: a one- or two-sentence summary of what the server does and when the agent should use it.
    • Server URL: the HTTPS endpoint of the MCP server.
    • Authentication: choose the authentication method the server requires, and enter the credentials or configuration values that method needs.

  6. Select Add to connect.

    Copilot Studio contacts the MCP server, negotiates the protocol handshake, and then lists the tools the server exposes.

  7. Review the list of tools that appear.

    For each tool, verify the name and description. If a tool doesn't have a clear description, agent responses that involve the tool are less reliable. Ask the MCP server author to improve the description before you rely on the tool in production.

  8. Select Save to finish adding the server.

The server appears in the agent's Tools list on the Build tab.

Test the server

After you add the server, test it before you publish the agent.

  1. Select the Preview tab.

  2. Ask the agent a question that requires one of the server's tools.

  3. Review the agent's response. Open the activity trace to verify which tool was invoked, what arguments were passed, and what the tool returned. See Use the activity trace to debug your agent.

If the agent doesn't invoke the tool when you expect it to, refine the tool name, the tool description, or the agent's instructions. See Configure agent details and instructions.

Manage the server after adding it

To remove an MCP server or turn one off temporarily, use the standard tool management flow. See Manage and delete tools in an agent.

If a server's URL, authentication, or exposed tools change after you add it, edit the server entry in the same Tools dialog to refresh the connection and re-read the tool list.

Limits

  • Each agent can connect to multiple MCP servers, but the total number of MCP server instances that can run concurrently in a single conversation is capped. If you attach more MCP servers than the cap allows and the agent tries to use them all in the same turn, the extra servers are skipped and their tools aren't available for that turn.
  • Keep the number of MCP servers attached to any single agent small, and remove servers you no longer use, so that the agent has room to invoke the servers you care about.
  • Each MCP server counts against the total number of tools an agent can host.
  • Last updated on