add-mcp

To use a custom registry with the add-mcp CLI, your server must implement a registry-compatible API. The CLI performs a GET request to your configured url using the following query parameters:

• search: The user's search keyword (lowercased)
• version: latest
• limit: 100
• source: cli

The endpoint must return a JSON object containing a servers array with the following schema:

{
  "servers": [
    {
      "server": {
        "name": "example-server",
        "description": "An example MCP server",
        "version": "1.0.0",
        "remotes": [
          {
            "type": "streamable-http",
            "url": "https://mcp.example.com/mcp"
          }
        ]
      }
    }
  ]
}

Once implemented, add your registry to ~/.config/add-mcp/config.json:

{
  "url": "https://my-registry.example.com/api/v1/servers",
  "label": "My custom registry"
}

The add-mcp project uses a high-security publishing pipeline that prohibits publishing from local machines. Instead, it relies on npm Trusted Publishing (OIDC) and staged publishing to ensure that every version is cryptographically signed and manually approved.

The workflow follows these stages:

1. GitHub Release: A maintainer creates a GitHub Release with a v* tag.
2. CI Execution: GitHub Actions runs release.yml, which builds the project and executes npm stage publish --provenance. This creates a short-lived OIDC token for authentication.
3. Staging: The package enters an npm staging area but is not yet live on the registry.
4. Manual Review: The maintainer inspects the staged tarball using the npm stage CLI.
5. WebAuthn Approval: The maintainer approves the release using a phishing-resistant WebAuthn/passkey. Only then does the package go live with a Sigstore provenance attestation.

flowchart LR
    devCommit[Commit on main] --> ghRelease["Maintainer publishes GitHub Release vX.Y.Z"]
    ghRelease --> tagProt["Tag-protection rule allows tag"]
    tagProt --> ciRun["release.yml runs on GitHub-hosted runner"]
    ciRun --> oidc["GitHub mints OIDC token (id-token: write)"]
    oidc --> npmStage["npm stage publish --provenance"]
    npmStage --> staging["Package sits in npm staging area"]
    staging --> review["Maintainer: npm stage view add-mcp"]
    review --> approve["npm stage approve add-mcp (WebAuthn)"]
    approve --> live["Live on registry.npmjs.org with provenance"]

You can preconfigure agents to automatically approve MCP tool calls using the --auto-approve flag. This is useful for servers that already have internal security gating.

• All Tools: Using --auto-approve without additional flags approves all tools for supported agents.
• Specific Tools: Use --approve-tool <tool_name> (repeatable) to approve only specific tools. This is the most reliable method for Claude Code due to known issues with all-tool rules.

Agent-Specific Implementation

• Codex: Writes approval modes into config.toml (either per-tool or a default_tools_approval_mode).
• Claude Code: Writes permission allow rules to a settings file (.claude/settings.local.json for projects or ~/.claude/settings.json for global).

# Auto-approve all tools for Codex and Claude Code
npx add-mcp "executor mcp" --name executor -a codex -a claude-code --auto-approve

# Auto-approve only the 'execute' tool for Codex
npx add-mcp "executor mcp" --name executor -a codex --auto-approve --approve-tool execute

The CLI stores registry configurations in ~/.config/add-mcp/config.json (respecting XDG_CONFIG_HOME). The first time you run find or search, the default add-mcp registry is saved automatically.

Built-in Registries

• add-mcp registry: https://add-mcp.com/registry/api/v1/servers (sourced from integrations.sh)
• Official Anthropic registry: https://registry.modelcontextprotocol.io/v0.1/servers

Adding a Custom Registry

To add a custom registry, append an entry to the findRegistries array in your config file. The registry must implement a GET endpoint that accepts search, version, and limit query parameters and returns a JSON object containing a servers array with the appropriate schema.

{
  "version": 1,
  "findRegistries": [
    {
      "url": "https://my-registry.example.com/api/v1/servers",
      "label": "My custom registry"
    }
  ]
}