Edit

Debug MCP and API plugins locally

Plugins enable declarative agents in Microsoft 365 Copilot to call Model Context Protocol (MCP) servers or REST APIs to retrieve data and perform tasks. Microsoft 365 Copilot must reach the MCP or API server over the internet. Typically, debugging tools host debug sessions on localhost (127.0.0.1), which is only accessible from the machine running the debugging tool. By using a reverse proxy, such as dev tunnels, you can expose your debug session to the internet to enable debugging calls from Microsoft 365 Copilot.

This article shows you how to use the devtunnel tool to enable local debugging for your MCP server or API.

Note

Your debugging tools may already provide a reverse proxy solution. We recommend checking the documentation for your developer tools to confirm. For example, if you created a new API using Microsoft 365 Agents Toolkit, the toolkit handles configuring reverse proxy for you.

Prerequisites

  • The devtunnel CLI installed on the machine where you host your debug sessions
  • The HTTP port number used by your debugging tool

Create a persistent dev tunnel

The devtunnel CLI enables you to create a persistent dev tunnel - a tunnel that you can stop and start as needed without the hosted URL changing. Using a tunnel with a persistent URL simplifies debugging for plugins since you don't need to update your declarative agent app packages with new URLs.

  1. If you aren't already logged in to the devtunnel CLI, use devtunnel user login --help to see the available options. Log in to the CLI before proceeding.

  2. Create the tunnel, allowing anonymous access. Anonymous access is necessary to allow Microsoft 365 Copilot to access your tunnel and is unrelated to any authentication required by your API.

    devtunnel create --allow-anonymous

    Tip

    Creating a new tunnel switches your default tunnel to the newly created one. This allows you to omit the tunnel-id argument to subsequent commands. If you create multiple tunnels you may need to use the tunnel-id argument to ensure you are using the expected tunnel. For more information, use the devtunnel --help command or see Dev tunnels command-line reference.

  3. Add the HTTP port number used by your debugging tool. Replace <port> with your port number, and set the --protocol parameter to https if your debugging tool is using HTTPS on the port, or http if it isn't using HTTPS.

    devtunnel port create --port-number <port> --protocol https

  4. Start the dev tunnel.

    devtunnel host

  5. For the first time running this dev tunnel, copy the URL labeled Connect via browser. Open this URL in your browser and select Continue to enable the tunnel.

    Note

    After selecting Continue, your browser will display an error. This is expected and can be ignored.

Once the tunnel is enabled, you can stop the tunnel with CTRL + C. You can restart the tunnel with the devtunnel host host-id command.

Using the dev tunnel

To use your dev tunnel for debugging, sideload an app package with the dev tunnel's URL in place of the server's URL.

Set the url property of the MCP server spec object inside your plugin manifest.

"runtimes": [
  {
    "type": "RemoteMCPServer",
    "spec": {
      "url": "<your-dev-tunnel-url>",
    }
  }
]

If you're using Agents Toolkit in Visual Studio Code to manage your declarative agent, you can add an environment variable to the /env/.env.dev.user file named PLUGIN_SERVER_URL and use that in place of your dev tunnel URL. Use the Provision step in the Lifecycle pane to sideload your agent. In your /env/.env.dev.user file, add:

OPENAPI_SERVER_URL=<your-dev-tunnel-url>

In your plugin manifest, update the url property:

"runtimes": [
  {
    "type": "RemoteMCPServer",
    "spec": {
      "url": "${{PLUGIN_SERVER_URL}}",
    }
  }
]

If you're not using Agents Toolkit, you can generate a new app package ZIP file and upload your agent.

  • Last updated on