How to Fix the Azure DevOps MCP Server Startup Error

Fix an Azure DevOps MCP startup error by first identifying the failing layer: server process, client connection, authentication, authorization, tool loading, or the assistant itself. The two server modes have different configuration and authentication: the hosted remote server uses HTTP and Microsoft Entra ID, while the local package uses stdio and supports local authentication options. Don’t combine their configuration shapes. [Microsoft’s remote troubleshooting guide] [Maintainer troubleshooting guide]

Before changing anything, record the client, operating system or environment, remote or local mode, exact error, and relevant client output logs. Then follow the branch below that matches the first failing step.

1. Identify which failure you have

Symptom	Likely layer to investigate first
The server process exits or never launches	Local command, Node.js version, package access, or configuration syntax
The client reports a connection or URL error	Remote endpoint and HTTP support, or local stdio command and client configuration
It says connected, but tool calls fail	Authentication flow, tenant, or permissions; connection status alone does not prove authorization
Tools are absent	Client tool support, filters, duplicate definitions, or tool loading
Tools run but return no expected data	Project/resource permissions, organization, or resource identifier
The assistant fails before any tool call	Assistant or client orchestration, rather than the Azure DevOps MCP server

Microsoft’s remote service is for Azure DevOps Services. The documented remote and local MCP servers do not support Azure DevOps Server on-premises. [Microsoft troubleshooting: scope and diagnostics]

2. Choose the correct server mode

Mode	Transport and configuration	Authentication and requirements
Hosted remote	Streamable HTTP; configure `type` as `http` and use `https://mcp.dev.azure.com/<organization>`.	Microsoft Entra ID OAuth. The organization must meet Microsoft’s Entra prerequisites, and the client must support the required sign-in flow. No local server installation is needed. [Remote setup guide]
Local package	stdio; configure a command such as `npx` with package arguments and the organization name.	Requires Node.js and package execution. Documented authentication choices include interactive OAuth, a PAT supplied through an environment variable, and Azure CLI authentication. [Getting started] [Troubleshooting]

Client compatibility matters. Microsoft’s current remote troubleshooting guide says Codex and Claude Desktop do not support the Entra authentication flow required by its hosted remote server, and Microsoft documents local stdio setup for Codex. Check the current Microsoft setup guide when publishing or configuring a client because compatibility can change. [Remote troubleshooting] [Local setup]

3. Fix the remote HTTP server configuration

Use the organization-specific endpoint, replacing the placeholder with the Azure DevOps organization name only:

https://mcp.dev.azure.com/<organization>

The client configuration needs HTTP transport. The exact configuration file and surrounding JSON vary by MCP client; use that client’s documented format, but preserve this endpoint and transport shape. Do not configure the remote server as a local command with npx.

Confirm the endpoint is exactly https://mcp.dev.azure.com/<organization>, with no braces and the correct organization spelling.
Confirm the client supports Microsoft Entra authentication for the hosted server and is configured with type: "http".
Verify the signed-in account can access the organization and target project.
Check outbound HTTPS access, proxy or firewall rules, and VPN behavior for mcp.dev.azure.com.
Restart or reload the MCP client after changing its configuration.

A root endpoint without an organization is a special case: the organization must then be supplied with each tool call. Prefer the organization-specific URL unless you deliberately need that behavior. Guest users should use the organization-specific endpoint. [Microsoft remote troubleshooting]

Remote authentication is Microsoft Entra OAuth. A PAT is not a substitute for this flow. If the browser sign-in prompt never appears or the redirect cannot complete, verify client support and whether the environment can open and return from the browser flow. For a client that cannot use the hosted authentication flow, configure the local server instead.

4. Fix the local stdio server configuration

The current setup invokes the package through npx and passes the organization name. A minimal command shape is:

npx -y @azure-devops/mcp <organization>

Use your client’s local MCP configuration format to set the executable to npx and the arguments to -y, @azure-devops/mcp, and your organization name. Don’t put the remote HTTP URL in this local command configuration.

Check that Node.js is version 20 or later if package installation or startup fails, as the maintainer troubleshooting guide recommends.
Confirm npx is available in the environment where the MCP client launches its subprocess. GUI clients may not inherit the same PATH as an interactive terminal.
Verify the organization argument and package name, then inspect the client’s MCP output log for process launch errors.
Keep the server definition in one intended configuration location. The maintainer guide warns that defining it in both a project mcp.json and VS Code settings can create duplicate servers or tool-limit problems.
Reload or restart the client after editing the configuration.

If startup is happening in WSL2, SSH, Docker, or CI, decide how authentication will work before interpreting “Connected” as success. Interactive OAuth can fail in a headless environment because its browser redirect is unavailable, even when the process starts. Use the non-interactive PAT environment-variable or Azure CLI mode documented by the maintainer when appropriate. [Maintainer troubleshooting]

5. Diagnose authentication and authorization separately

Remote use depends on Entra OAuth and an Entra-backed organization. Read the full AADSTS code and follow the action for that specific code; the prefix alone does not identify the fix. Microsoft’s examples include:

Error	What to investigate
`AADSTS50076`	Multifactor authentication is required. Complete the required sign-in challenge.
`AADSTS700016`	The application was not found in the tenant. Check tenant and application availability.
`AADSTS65001`	Consent is missing. Follow the organization’s consent process.
`AADSTS50105`	The user is not assigned to the application. Check assignment with the tenant administrator.

If the Azure DevOps MCP enterprise application is missing from the tenant, Microsoft documents a service-principal creation procedure using Azure CLI. That requires an administrator role, so involve a tenant administrator rather than treating it as a client-side startup change. [Microsoft error reference and service-principal procedure]

Local OAuth fails in a headless environment

For local MCP, a process can start and show connected while a later tool call fails with fetch failed because interactive OAuth cannot complete its browser redirect. Use one of the non-interactive modes documented by the package. Do not apply these local options to the hosted remote HTTP configuration. [Maintainer troubleshooting]

PAT environment-variable mode: Set ADO_MCP_AUTH_TOKEN in the environment inherited by the local MCP process and configure the server with --authentication envvar. Keep the token out of checked-in configuration, shell history, and logs. Use the package’s current documentation for the required token permissions and exact client-specific environment syntax.
Azure CLI mode: Sign in with Azure CLI using the account and tenant that can access the organization, then configure the local server with --authentication azcli. For multiple tenants or guest access, check which tenant the CLI is using.

Authentication proves the identity; it does not grant access to every organization, project, or resource. Check that the signed-in account belongs to the Azure DevOps organization, has project membership, and can view the requested data. For guest users, verify tenant guest membership and project permissions as well.

For local multi-tenant cases, the maintainer guide describes TF400813 when Azure CLI can list projects but MCP calls still fail. Inspect the active CLI tenant; pass --tenant <tenant-id> where required so the process authenticates against the organization’s tenant. [Maintainer troubleshooting]

6. Restore missing tools or empty results

A connected indicator only shows that a connection was established; it does not establish that the client loaded the tools or that the account can read the requested data.

Confirm the client exposes MCP tools in the current mode. In GitHub Copilot, use agent mode; standard chat mode does not expose MCP tools according to Microsoft’s remote troubleshooting guide.
Inspect tool selection, allowlists, filters, and whether another server definition is shadowing or duplicating this one.
If using remote tool filters, set either X-MCP-Toolsets or X-MCP-Tools, not both. Microsoft documents them as mutually exclusive. Restart the assistant after changing filters.
Try a simple, read-only request that explicitly asks to list Azure DevOps projects. If that works, ask for a specific project or resource and check its identifier and your permissions.
If tools are missing after editing configuration, reload the MCP client and inspect its MCP or GitHub Copilot Output channel for tool loading and authentication details.

If the assistant fails before it invokes any MCP tool, Microsoft classifies that as outside the Azure DevOps MCP boundary. Restart the assistant; if it continues, use the client provider’s troubleshooting path. [Microsoft remote troubleshooting]

7. Use client logs to find the first failing step

In VS Code, inspect the MCP or GitHub Copilot Output channel. Look for the earliest error, rather than relying only on the final “connected” or “failed” status. Preserve timestamps and redact access tokens, cookies, and authorization headers before sharing logs.

Classify the first error:

Executable or spawn error: local command, PATH, Node.js, package download, or malformed configuration.
HTTP connection, DNS, TLS, or timeout error: remote URL, network, proxy, VPN, or firewall.
OAuth or AADSTS error: remote Entra sign-in, tenant, consent, MFA, or assignment.
fetch failed after local connection: investigate the local authentication flow, especially headless OAuth.
TF400813: check local Azure CLI tenant and Azure DevOps authorization.
No tool invocation appears: client tool support, assistant mode, tool filters, or orchestration.

8. Troubleshooting quick reference

Error or symptom	Likely cause	Fix
Remote URL error or timeout	Wrong organization endpoint or blocked outbound HTTPS	Use `https://mcp.dev.azure.com/<organization>`, set HTTP transport, and check proxy, firewall, VPN, and DNS access.
Local process not found or exits immediately	Invalid command, missing Node.js/ `npx`, package failure, or bad arguments	Check Node.js 20+, executable PATH, package name, organization argument, and client log.
Connected, then `fetch failed`	Local interactive OAuth redirect cannot complete in a headless environment	Configure documented local envvar PAT or Azure CLI authentication.
Remote sign-in never starts	Client does not support the required Entra flow, or browser redirect is stuck	Check current client compatibility; use local stdio for an unsupported client. In VS Code, clear stale credentials or reload the window if its interactive sign-in is stuck.
`AADSTS` denial	Specific Entra condition such as MFA, missing app, consent, or assignment	Use the remedy for the exact error code; involve the tenant administrator when required.
`TF400813` in local mode	Wrong Azure CLI tenant or insufficient Azure DevOps membership	Check the organization tenant, use `--tenant <tenant-id>` where needed, and verify project permissions.
Connected but no tools	Unsupported client mode, filters, duplicate server, or tools not reloaded	Check client tool support and filters, remove duplicate definitions, then reload the assistant.
Tools return empty or incomplete data	Wrong project/resource or insufficient permission	Use an explicit resource identifier and verify organization, project membership, and access.
Assistant errors before a tool call	Client or assistant orchestration failure	Restart the assistant and consult the client provider if it persists.

9. Performance, reliability, and operational notes

For remote mode, network path and identity-provider redirects can affect whether a request reaches the service. For local mode, startup also depends on the client’s subprocess environment, Node.js/package availability, and how credentials are provided. These are diagnostic considerations, not a guarantee that any one factor caused a particular error.

To make setup more reliable, keep one server definition, use the mode the client supports, select an authentication method that works in the execution environment, and keep the organization and tenant explicit. After a configuration change, restart the client and make a small read-only call before relying on write-capable tools. Store credentials in the client’s supported secret or environment mechanism and redact them from logs.

The maintainer troubleshooting page also notes a tool limit of 128 in the relevant configuration context. Treat it as a tool-loading/configuration limit: remove unnecessary duplicate definitions and filters if tools are missing, and consult the current guide for the exact limit behavior. [Maintainer troubleshooting]

10. An unrelated screenshot task? Use ScreenshotNeo

If your development workflow also needs website screenshots, ScreenshotNeo is a website screenshot API and MCP server for developers. Its MCP server provides take_screenshot, get_page_info, and capture_pdf for Claude, Cursor, and other MCP clients. This does not fix Azure DevOps MCP startup or authentication.

FAQ

Does “Connected” mean authentication is working?

No. A process or transport connection can succeed while later authentication, authorization, or tool loading fails. Test a read-only tool call and inspect its error.

Can I use a PAT with the hosted remote server?

No. The remote hosted service uses Microsoft Entra OAuth. PAT environment-variable authentication is a documented option for the local package.

What details should I include when asking for help?

Include the client and version, local or remote mode, operating environment, redacted configuration shape, exact error text, and the earliest relevant log entry. Never include a PAT, access token, cookie, or authorization header.

Or skip the browser setup

For website screenshot work, ScreenshotNeo can capture a URL with one GET request. See the ScreenshotNeo API docs for parameters and response details.

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

Cookie banners, popups, and chat widgets are removed before the shot. Bot checks, blank pages, and failed loads are never billed. An MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Sign up for free.