MCP server

The Model Context Protocol (MCP) server provides a standardized interface that lets compatible AI agents query your Dev Herald health report data in a simple and secure way.

Connect natively in Cursor and other clients that support remote MCP, or use the mcp-remote module for clients that do not.

Dev Herald’s MCP server follows the authenticated remote MCP spec . The server is centrally hosted and uses OAuth 2.1 with dynamic client registration. When you authorize, you choose one workspace — MCP can read health reports for all projects in that organization.

Setup instructions

General

The server supports Streamable HTTP transports and authenticates via OAuth at:

https://dev-herald.com/api/mcp

For local development against a running app, use http://localhost:3000/api/mcp instead.

On first connect you sign in to Dev Herald and approve access. If you belong to more than one workspace, the consent screen asks you to pick which organization MCP can access. If you only have one workspace, it is selected automatically.

Prerequisites: a Dev Herald account and health reports running in CI for the projects you want to query.

Cursor

Add the MCP server in Cursor Settings → MCP, or edit .cursor/mcp.json:


{
  "mcpServers": {
    "dev-herald": {
      "url": "https://dev-herald.com/api/mcp"
    }
  }
}

Install in Cursor

The first time Cursor connects, complete the OAuth flow in your browser. After that, the server is available in any chat where MCP is enabled.

Visual Studio Code


{
  "mcpServers": {
    "dev-herald": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://dev-herald.com/api/mcp"]
    }
  }
}

Ctrl/Cmd + Shift + P and search for MCP: Add Server.
Select Command (stdio).
Enter: npx -y mcp-remote https://dev-herald.com/api/mcp
Name the server Dev Herald and start it from MCP: List Servers.

Others

Many MCP clients can connect with the same remote URL. For clients that only support stdio, use:

Command: npx
Arguments: -y mcp-remote https://dev-herald.com/api/mcp
Environment: None

Complete the OAuth sign-in when prompted.

Example prompts

Once connected, ask your agent about health reports in the authorized workspace:

“What CVEs are open on our web app?”
“Show unused dependencies from the latest health run for the API service.”
“Which bundle routes regressed since the last report?”
“Summarize health findings across our projects in this workspace.”

FAQ

How do I switch to a different workspace?

Remove the Dev Herald MCP server in your client and add it again. Go through consent and pick a different organization.

Why am I seeing an authentication error when connecting?

Clear saved MCP auth and try again:


rm -rf ~/.mcp-auth

Then reconnect and complete the OAuth flow. Ensure you are using a recent version of Node.js if your client relies on mcp-remote.

Does the MCP server support Streamable HTTP?

Yes, at https://dev-herald.com/api/mcp (or http://localhost:3000/api/mcp for local development).

Can I use a project API key instead of OAuth?

No. MCP uses OAuth scoped to your Dev Herald account and a selected workspace. Project API keys are for CI integrations (health ingest, PR comments) — not for MCP.

What data can MCP access?

Read-only access to health reports for projects in the workspace you authorized — CVEs, unused code, bundle metrics, and related CI signals. See Health Reports and Data & Privacy for details.

Health Reports — signals collected and how reports are ingested
Cleanup with Cursor — act on findings from the dashboard