How to Fix Failed Connections to the Microsoft Copilot API MCP Server

A failed Microsoft Copilot MCP connection can originate in four different stages: reaching the endpoint, exchanging credentials, discovering tools, or invoking a tool. First identify the host surface you are using: a Microsoft 365 Copilot plugin, a Microsoft 365 Copilot MCP app, or Copilot Studio MCP integration. Their manifests, authentication settings, transport requirements, and troubleshooting paths differ. Do not apply a plugin-manifest fix to Copilot Studio without checking the relevant documentation.

The fastest path is to expose the error in developer mode, classify the failure stage, then compare the endpoint and authentication values across every configuration location.

1. Identify the Copilot integration surface

Surface	What to inspect	Typical evidence
Microsoft 365 Copilot plugin	Plugin manifest, Microsoft Enterprise token store authentication configuration, MCP endpoint or OpenAPI server URL	Authentication errors, empty Actions list, token or base URL mismatch
Microsoft 365 Copilot MCP app	MCP endpoint, manifest tool declarations, discovery settings, authentication	“No tools listed,” tools withheld during validation
Copilot Studio MCP	Open SSE connection response, transport URI, tool JSON schema	Invalid endpoint URI or filtered/incompatible schema

Microsoft documents separate troubleshooting for these surfaces: plugin authentication, MCP apps, and Copilot Studio MCP.

2. Expose the real error

In Microsoft 365 Copilot, enable developer mode. Microsoft’s documented instruction is: “To see authentication errors in agent responses, enable developer mode.”
Open the debug information card in the agent response.
Check the Actions section for the tools available to the agent.
Record the HTTP status, endpoint, authentication method, and whether the tool list is empty before changing configuration.

A generic “connection failed” message is not enough to select a fix. Use the observed symptom and status code to choose the next branch.

3. Diagnose the failure stage

Endpoint or transport failure

Confirm that the MCP server is running and that the manifest points to the exact MCP endpoint. For an API plugin, verify the OpenAPI server URL instead. Check DNS, TLS, firewall, proxy, and whether the endpoint is reachable from Microsoft’s service rather than only from your laptop.

Authentication or token exchange failure

Compare the OAuth provider, Microsoft auth configuration, and plugin manifest as a set. Microsoft identifies mismatches among these three locations as the most common source of sign-in failure.

Discovery or validation failure

If the endpoint responds but no tools appear, verify authentication first: some servers return no tools until sign-in succeeds. Then check that tools/list returns the expected tools and that runtime validation has not withheld them.

Invocation failure

If tools are listed but do not trigger, inspect the manifest tool names, descriptions, run_for_functions values, input schema, and the request sent by the runtime. A discovery success does not prove that invocation authorization or argument validation will succeed.

4. Fix “No tools listed”

Verify the MCP process is running and the URL in the manifest is correct.
Call the server’s MCP discovery endpoint using the transport required by your integration and confirm that tools/list returns tools.
Confirm that authentication completes before discovery. Inspect developer-mode diagnostics for a hidden 401 or token error.
For dynamic discovery, configure the runtime with run_for_functions: ["*"] and an empty top-level functions array.
For pinned tools, verify every manifest functions entry, its description, and its run_for_functions tool name.
Check runtime validation logs for a tool that was withheld because its schema or declaration was rejected.

Keep the declared tool name, server tool name, and invocation name identical. A typo can leave the endpoint healthy while the Actions list remains empty or a tool never triggers.

5. Compare OAuth settings in all three places

For Microsoft 365 Copilot plugins, compare these values without normalizing them by guesswork:

Location	Value to verify
OAuth provider	Client/application registration, redirect URI, scopes, and registered base URL
Microsoft auth configuration	Base URL, provider details, and configuration ID
Plugin manifest	MCP `url` (or OpenAPI server URL) and authentication reference

The auth-config Base URL must match the MCP server url in the manifest, or the relevant OpenAPI server URL.
Register https://teams.microsoft.com/api/platform/v1.0/oAuthRedirect with the OAuth provider.
Make the runtime auth.reference_id equal the auth-configuration ID in the Teams developer portal.
Confirm app and organization usage restrictions allow the app and the current tenant.

Microsoft’s authentication overview describes Entra SSO, OAuth 2.0, and anonymous authentication for MCP and API plugins; DCR is for MCP plugins, while API keys are for API plugins. Agent connector authorization is a separate configuration surface.

6. Interpret common status-specific errors

Observed error	Cause	Fix
HTTP 307 from token endpoint	The token endpoint redirects	Use a direct token endpoint. Microsoft documents HTTP 307 token responses as unsupported in this flow.
App ID mismatch	Plugin App ID differs from OAuth or SSO registration	Compare the IDs character for character and update the incorrect registration or manifest.
Base URL mismatch	Manifest URL differs from the registered OAuth base URL	Use the same base URL in the manifest, auth configuration, and provider registration.
Missing or incorrect `reference_id`	Runtime points at a different auth configuration	Set `auth.reference_id` to the auth-config ID in the Teams developer portal.
Organization policy restriction	Tenant or app access is blocked	Ask an administrator to review app and organization access policies.

When an on-behalf-of flow needs user consent to another API, Microsoft instructs the server to return 401 Unauthorized so Copilot can prompt the user to sign in and grant consent. Do not replace that response with a generic success payload.

For Entra SSO, verify the application ID URI, consent redirect URI, and Microsoft Enterprise token store client. To clear stored OAuth credentials, sign out in Chat settings > Agents. Entra SSO tokens can persist because of caching or tenant and client settings; Microsoft points to removing consent or revoking sessions when forced reauthentication is required.

A popup that authenticates successfully but remains open often loses its window.opener reference during the redirect chain.

Open developer tools for the popup.
Inspect window.opener after each redirect.
Use the Network tab to find the response that changes the opener relationship.
Check for Cross-Origin-Opener-Policy: same-origin headers.
Check whether a redirect link or navigation uses rel="noopener".
Adjust the redirect chain or headers so the opener remains available for the completion message, while preserving your security requirements.

9. Copilot Studio MCP transport and schema checks

Copilot Studio has separate known issues even when the MCP server works elsewhere.

The endpoint returned by the Open SSE connection call must be a full URI, including its scheme and host.
exclusiveMinimum must be Boolean.
A type field should contain only one type value.
Reference-type inputs and outputs are unsupported and may be filtered.
Enum inputs are interpreted as strings.

These are documented compatibility constraints; the Copilot Studio troubleshooting page does not provide a workaround for every schema case. Simplify the published schema or expose a compatible wrapper when a tool is filtered.

10. A repeatable diagnostic checklist

Name the host: Microsoft 365 Copilot plugin, MCP app, or Copilot Studio.
Enable developer mode and save the debug card.
Classify the stage: endpoint, authentication, discovery, validation, or invocation.
Check the exact URL and transport from the host’s documentation.
Compare OAuth provider, auth config, and manifest values.
Test redirect URI, App ID, base URL, and reference_id.
Confirm tenant and organization policy access.
For missing tools, verify authentication, tools/list, runtime discovery settings, and manifest declarations.
For popup hangs, inspect window.opener, COOP headers, and noopener.
For Copilot Studio, validate the full SSE URI and supported JSON schema.
Retest one change at a time and keep the successful configuration values.

11. Reliability and operational notes

Keep health checks separate from tool discovery so an endpoint can be monitored without invoking user actions. Log correlation IDs, status codes, token endpoint responses, selected auth configuration, and the tool name requested. Redact access tokens and authorization headers.

Use direct, non-redirecting token endpoints and stable HTTPS URLs. Validate manifests and schemas in CI before publishing. If a server supports multiple tenants, test a tenant with restrictive policy as well as an unrestricted development tenant. Cache only non-sensitive metadata; stale tool lists can hide a corrected deployment.

12. Or skip the browser setup

If your workflow only needs reliable website images for diagnosing an MCP-powered interface, ScreenshotNeo provides a single HTTP request instead of maintaining browser automation. It accepts consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and each response identifies the result with X-Page-Verdict and X-Billed headers.

Read the ScreenshotNeo API documentation for the complete option list. cURL:

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

Python:

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

Node.js:

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

ScreenshotNeo also provides an MCP server with take_screenshot, get_page_info, and capture_pdf for Claude, Cursor, and other MCP clients. It supports full-page and element captures, custom CSS and JavaScript, waits, request blocking, headers, cookies, user agents, geolocation, PDF settings, caching, signed links, async jobs, bulk capture, and a usage API. The Free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account.

FAQ

Why does Copilot say the server is connected but show no tools?

Authentication or discovery can still be failing. Check the debug card, confirm tools/list returns tools, and verify dynamic or pinned manifest configuration.

Can I use an HTTP 307 token endpoint?

No. Microsoft documents a 307 response from the token endpoint as unsupported; configure a direct endpoint.

Are Copilot Studio and Microsoft 365 Copilot MCP settings interchangeable?

No. They are separate integration surfaces with different transport and schema constraints.

Return HTTP 401 Unauthorized so Copilot can initiate sign-in and consent.

Why did a tool disappear after deployment?

Runtime validation may have withheld it, or its schema may violate Copilot Studio compatibility rules. Inspect validation diagnostics and simplify unsupported schema constructs.