Scan a project directory to detect the tech stack and recommend MCP servers.

This is the best starting point. Analyzes project files (package.json, pyproject.toml, docker-compose.yml, .env, Dockerfile, etc.) to identify languages, frameworks, databases, and services in use, then recommends MCP servers that would be useful for that stack.

Results are cross-referenced with already-installed servers so you can see what's missing. Use configure_server to install recommended servers.

Args: path: Path to the project directory to scan. Defaults to current directory ("."). client: Which MCP client's config to check for already-installed servers. One of "claude_desktop", "claude_code", "cursor", "windsurf". Auto-detects if not provided.

Returns: Dict with: detected_technologies, env_vars_found, recommendations (each with already_installed flag), and a human-readable summary.

Search the MCP Registry for servers matching a keyword.

Use this when the user asks for a specific server or technology. Pass project_path to automatically rank results by relevance to the project's detected tech stack — each result gets a "relevance" field ("high", "medium", "low") and a "match_reason" explaining the score.

When evaluate is True (default), each result also gets a "maturity" field with GitHub-based quality signals (stars, last commit, tier). Set evaluate=False for faster results without GitHub API calls.

After finding the right server, use configure_server with the package_identifier and registry_type from the results to install it.

Args: query: Search term (e.g. "postgres", "github", "slack", "docker"). limit: Maximum results to return (1-50, default 10). project_path: Optional project directory path. When provided, results are ranked by relevance to the detected tech stack and include credential_status for each result. evaluate: Whether to fetch GitHub maturity signals for each result (default True). Set to False for faster searches.

Returns: List of servers, each with: name, description, version, registry_type, package_identifier, transport, is_official, env_vars_required, repository_url, and source ("official" | "smithery" | "both"). When project_path is set, also includes relevance, match_reason, and credential_status. When evaluate is True, also includes maturity. All results include deterministic ranking metadata: intent_match_score, intent_match_reason, composite_score, and composite_breakdown. Smithery results also include use_count (popularity) and verified (quality badge).

List all MCP servers currently configured in your AI client.

Use this to see what servers are already set up before adding new ones with configure_server, or to find the exact server name needed for test_connection or remove_server.

Secret-looking environment variable values (API keys, tokens) are automatically masked as "***" in the output.

Args: client: Which MCP client's config to read. One of "claude_desktop", "claude_code", "cursor", "windsurf". Auto-detects if empty. project_path: Optional project directory containing mcp-tap.lock. When provided, output is enriched with canonical identity fields (package_identifier, registry_type, repository_url) for matched servers.

Returns: List of configured servers, each with: name, command, args, env (masked), and config_file path.

Test that a single configured MCP server starts and responds correctly.

Spawns the server process, connects via MCP stdio protocol, calls list_tools() to verify it responds, then shuts it down cleanly.

Use this to verify a specific server after configure_server, or to debug a server that check_health reported as unhealthy.

Args: server_name: Exact name of the server as it appears in the config. Use list_installed to see available names. client: Which MCP client's config to read from. One of "claude_desktop", "claude_code", "cursor", "windsurf". Auto-detects if empty. timeout_seconds: Max seconds to wait for a response (clamped to 5-60). Default 15. Increase for slow-starting servers. auto_heal: When True, if the test fails, attempt to diagnose the error, apply an automatic fix, and retry. Returns healing details alongside the test result.

Returns: Test result with success status, discovered tool names, or error message explaining what went wrong. If auto_heal is True and healing was attempted, includes a "healing" key with diagnosis and fix details.

Check the health of all configured MCP servers at once.

Reads every server from your MCP client config, tests them all concurrently (spawns each, connects via MCP protocol, calls list_tools()), and returns a health report.

Use this after configure_server to verify everything is working, or as a periodic health check. For unhealthy servers, try remove_server followed by configure_server to reinstall.

Args: client: Which MCP client's config to check. One of "claude_desktop", "claude_code", "cursor", "windsurf". Auto-detects if not specified. timeout_seconds: Max seconds to wait per server (clamped to 5-60). Default 15. Increase if servers are slow to start. auto_heal: When True, attempt to diagnose and fix each unhealthy server automatically. Healing results are included in each server's entry in the report.

Returns: Health report with: client, config_file, total/healthy/unhealthy counts, and per-server details (status, tools count, error). When auto_heal is True, unhealthy servers include a "healing" key.

Fetch an MCP server's documentation and extract configuration details.

Use this when search_servers returns incomplete data (missing env vars, unclear transport) or when you have a GitHub URL for a server not in the registry.

Fetches the README.md from the repository URL and extracts:

• Install commands (npm, pip, docker)

• Transport type (stdio, http, sse)

• Required environment variables with descriptions

• Command and args patterns

• Usage examples

The extracted data may be incomplete or ambiguous — use your judgment to fill gaps based on the raw README content also returned.

Args: repository_url: GitHub/GitLab repository URL (e.g. "https://github.com/modelcontextprotocol/servers").

Returns: Dict with: extracted_config (structured hints), raw_readme (first 5000 chars of README for LLM reasoning), and confidence (how much structured data was found).

Compare the lockfile against the actual installed MCP server state.

Reads mcp-tap.lock from the project directory and compares it against the servers configured in the target MCP client. Reports drift entries for any differences found.

Args: project_path: Root directory of the project containing mcp-tap.lock. client: Which MCP client's config to compare against. One of "claude_desktop", "claude_code", "cursor", "windsurf". Auto-detects if not specified.

Returns: Verification result with drift entries. clean=True means no drift was detected.

Install an MCP server package, add it to your client config, and verify it works.

This is the main action tool. It handles the complete setup flow:

1. Installs the package via npm/pip/docker (fails fast if install fails)

2. Validates by spawning the server and calling list_tools()

3. Writes the server entry to your MCP client config file(s) only if validation passes

For HTTP transport servers (streamable-http, SSE), the install step is skipped and the server is configured via the mcp-remote bridge. Pass the server URL as package_identifier (e.g. https://mcp.vercel.com) or set registry_type to "streamable-http", "http", or "sse".

Get the package_identifier and registry_type from search_servers results or scan_project recommendations.

If validation fails, the config is NOT written to avoid broken entries. The user should fix the issue and retry.

When dry_run=True, mcp-tap performs install + validation preflight but does NOT write any client config, lockfile, or telemetry acceptance event.

Args: server_name: Name for this server in the config (e.g. "postgres"). This is how it appears in list_installed and other tools. package_identifier: The package to install and run. Get this from search_servers results (e.g. "@modelcontextprotocol/server-postgres" for npm, "mcp-server-git" for pypi), or a URL for HTTP transport servers (e.g. "https://mcp.vercel.com"). clients: Target MCP client(s). Comma-separated names like "claude_desktop,cursor", "all" for every detected client, or empty to auto-detect the first available. registry_type: Package source — "npm" (default), "pypi", "oci", "streamable-http", "http", or "sse". version: Package version. Defaults to "latest". env_vars: Environment variables the server needs, as comma-separated KEY=VALUE pairs (e.g. "POSTGRES_URL=postgresql://...,API_KEY=sk-..."). Check search_servers results for env_vars_required. scope: "user" for global config (default), "project" for project-scoped config (e.g. .cursor/mcp.json in the project dir). project_path: Project directory path. Required when scope="project". feedback_query_id: Optional query_id from scan/search telemetry event so accepted recommendations can be linked to shown rankings. dry_run: When True, run preflight only (install/validate) and return what would be written without touching client config files.

Returns: Result with: success, install_status, config_written, validation_passed, tools_discovered. Multi-client calls also include per_client_results.

Remove an MCP server from your AI client's configuration.

Removes the server entry from the config file. The user must restart their MCP client for the change to take effect.

Use list_installed to see server names. Use clients="all" to remove from every configured client at once.

Args: server_name: Exact name of the server to remove, as shown by list_installed. clients: Target MCP client(s). Comma-separated names like "claude_desktop,cursor", "all" for every detected client, or empty to auto-detect. scope: "user" for global config (default), "project" for project-scoped config. project_path: Project directory path. Required when scope="project".

Returns: Result with success status and message. Multi-client calls also include per_client_results with per-client removal status.

Recreate MCP server configurations from a lockfile.

Reads mcp-tap.lock from the project directory and reinstalls each server into the target MCP client config. Environment variable values are NOT stored in the lockfile, so the user must set them manually.

Args: project_path: Root directory of the project containing mcp-tap.lock. client: Target MCP client(s). Comma-separated names like "claude_desktop,cursor", "all" for every detected client, or empty to auto-detect the first available. dry_run: When True, show what would be installed without actually installing or writing config.

Returns: Restore result with per-server status, required env vars, and overall success.

Install a group of MCP servers from a stack definition.

Stacks are shareable profiles that bundle multiple MCP servers together. Use a built-in stack name or a path to a .yaml file.

Built-in stacks: data-science, web-dev, devops. Use dry_run=True to preview what would be installed without making changes.

Args: stack: Built-in stack name (e.g. "data-science") or path to .yaml file. clients: Target MCP client(s). Same as configure_server. scope: "user" or "project". Same as configure_server. project_path: Project directory path. Required when scope="project". dry_run: If True, only show what would be installed without installing.

Returns: Result with: stack_name, servers_total, servers_installed, servers_failed, per_server_results, and any env_vars_needed.