mcp-watchtower

Analyze MCP servers for naming, routing, and semantic tool conflicts.

Docs: https://self-5d39fc87.mintlify.app/

mcp-watchtower can inspect a live MCP server, a remote MCP endpoint, or a JSON tool manifest and produce:

• static findings for duplicate names, naming inconsistencies, parameter conflicts, shadow patterns, and oversized tool surfaces
• semantic findings for tools that already exist in the broader MCP corpus or are likely to overlap with existing tools

Start here

• Get started
• CLI reference
• Checks overview
• API reference

Quick start

npx mcp-watchtower scan --server "uvx my-server"

CLI

# Local MCP server over stdio
npx mcp-watchtower scan --server "uvx my-server"

# Remote MCP endpoint
npx mcp-watchtower scan --remote "https://api.example.com/mcp" --auth-token "$MCP_TOKEN"

# Manifest / CI input
npx mcp-watchtower scan --manifest ./tools.json --name my-server

Useful flags

# JSON output
npx mcp-watchtower scan --server "uvx my-server" --json

# Treat static name collisions as critical
npx mcp-watchtower scan --server "uvx my-server" --platform

# Semantic overlap detection against the corpus index
npx mcp-watchtower scan --server "uvx my-server" --semantic

# Tune semantic sensitivity
npx mcp-watchtower scan --server "uvx my-server" --semantic --threshold 0.8

What it checks

Static analysis

• duplicate tool names
• inconsistent naming conventions
• conflicting parameter names for the same concept
• prompt-shadowing language in tool descriptions
• excessive tool counts

Semantic analysis

• ALREADY_IN_CORPUS — the tool appears to already exist in the corpus
• SEMANTIC_OVERLAP — the tool looks close to an existing tool and may need clearer disambiguation

Index behavior

Semantic analysis ships with a bundled fallback index in src/data/.

On CLI startup, mcp-watchtower also checks the published CDN manifest and, if a newer index is available, downloads it to:

~/.mcp-watchtower/index/

If the CDN is unavailable or the update fails, scans continue silently with the bundled index.

Exit codes

• 0 — no critical static findings
• 1 — one or more critical static findings

Semantic findings are informational or warning-level only and do not affect the exit code.

Library usage

import { SemanticAnalyzer, StaticAnalyzer } from 'mcp-watchtower'

const staticReport = new StaticAnalyzer().analyze('my-server', tools)
const semanticReport = await new SemanticAnalyzer().analyze('my-server', tools)

Developer workflow

npm run build
npm test
npm run pack:check
npm run crawl
npm run embed
npm run build-index
npm run publish-index

If you're working from a local clone instead of npm, build first and run the compiled CLI directly:

npm install
npm run build
node dist/cli/index.js scan --server "uvx my-server"

publish-index rebuilds the corpus, embeddings, and semantic index, then uploads the refreshed assets and manifest to Cloudflare R2. The nightly GitHub Actions workflow at .github/workflows/refresh-index.yml runs the same publish step automatically.

Releasing the package

mcp-watchtower should be released with Changesets, separate from the semantic index refresh pipeline.

1. Add a changeset in the same PR as any user-visible package change:

   npm run changeset

2. Merge the PR into main.

3. The release.yml workflow will open or update a chore: release package PR with the version bump and changelog changes.

4. Merge that release PR to publish the package to npm and create the matching GitHub Release.

First-time setup

1. Create an npm access token that can publish mcp-watchtower.
2. Save it as the repository secret NPM_TOKEN.
3. Ensure the package name is available on npm and that the publishing account has access to it.
4. Let GitHub Actions handle tags and GitHub Releases through the built-in GITHUB_TOKEN.

Release requirements

• Repository secret: NPM_TOKEN with permission to publish mcp-watchtower
• Built-in GITHUB_TOKEN handles the release PR, tags, and GitHub Release creation

When to add a changeset

• Add a normal changeset for any user-visible change to behavior, CLI flags, shipped assets, or public library APIs.

• If a PR should merge without producing a release, run:

  npx changeset --empty

  That records intentional "no release" work so reviewers and automation do not have to guess.

Local release validation

Before publishing manually or debugging the workflow locally, validate the release artifact with:

npm run build
npm test
npm run pack:check

If a release fails

• If the workflow fails before publishing to npm, fix the issue on main; the release PR will be regenerated or updated automatically.
• If npm publish fails because of auth or registry configuration, fix NPM_TOKEN or package permissions and rerun the workflow.
• If a version was tagged but npm did not receive the package, inspect the failed Actions logs before retrying so you do not attempt to republish an existing version.

Semantic index releases

The semantic index is intentionally released on its own cadence. .github/workflows/refresh-index.yml continues to rebuild and publish the Cloudflare R2 assets independently of npm package releases.