Documentation

Every AI application uses a different config format for MCP (Model Context Protocol) servers. Claude Desktop uses mcpServers, VS Code uses servers, Goose uses YAML with cmd/envs, Codex uses TOML with mcp_servers... there are 19 apps, 6 root keys, and 4 formats.

getmcp solves this with one canonical format, config generators for every app, a registry of popular servers, and a CLI that auto-detects your apps and writes the correct config.

Install any MCP server into all your detected AI apps with a single command:

npx @getmcp/cli add <server>

Here are the most common CLI commands:

# Install a server by official ID
npx @getmcp/cli add io.github.github/github-mcp-server

# Fuzzy search — unrecognized input triggers search
npx @getmcp/cli add github

# Browse available servers
npx @getmcp/cli list

# Search for servers by keyword
npx @getmcp/cli list --search=database

# Interactive fuzzy search
npx @getmcp/cli find

# Remove a server from all apps
npx @getmcp/cli remove

# Check installation status
npx @getmcp/cli check

# Update all tracked installations
npx @getmcp/cli update

# Diagnose config issues
npx @getmcp/cli doctor

# Adopt existing server configs into tracking
npx @getmcp/cli import

# Sync from project manifest (getmcp.json)
npx @getmcp/cli sync

# Manage custom registry sources
npx @getmcp/cli registry list
npx @getmcp/cli registry add https://mcp.example.com --name my-team

# Machine-readable JSON output
npx @getmcp/cli list --json

The CLI auto-detects which AI applications you have installed, prompts for any required environment variables, and merges the config into each app's config file. It never overwrites your existing configuration.

The CLI uses official server IDs (like io.github.github/github-mcp-server). If the input doesn't match an exact ID, the CLI performs a fuzzy search across server names, descriptions, and categories.

Teams can share MCP server configurations via a getmcp.json manifest file in the project root:

{
  "servers": {
    "io.github.github/github-mcp-server": {},
    "io.github.modelcontextprotocol/server-postgres": {
      "env": {
        "DATABASE_URL": "postgresql://localhost:5432/mydb"
      }
    }
  },
  "registries": [
    { "name": "my-team", "url": "https://mcp.example.com", "type": "private" }
  ]
}

Then any team member can install all declared servers into their detected apps with:

npx @getmcp/cli sync

The sync command reads the manifest, resolves each server from configured registries, merges any local overrides (like environment variables), and writes the correct config for every detected app.

Beyond the official registry, getmcp supports multiple registry sources — teams can host private registries or use third-party public ones.

Adding a registry

Register a new source with the registry add command. Use the --name flag to give it a friendly alias:

npx @getmcp/cli registry add https://mcp.example.com --name my-team

The CLI pings the registry's /v0.1/ping endpoint to detect whether it's public or private. Private registries require authentication (see below).

Listing registries

View all configured registries, including their type and status:

npx @getmcp/cli registry list

# Machine-readable output
npx @getmcp/cli registry list --json

Removing a registry

Remove a registry by name. This also cleans up any stored credentials for that registry:

npx @getmcp/cli registry remove my-team

Using a specific registry

When adding a server, use the --registry flag to install from a specific source:

npx @getmcp/cli add my-server --registry my-team

Private registries require authentication. The CLI supports three auth methods: bearer token, basic auth (username/password), and custom header.

Login

Authenticate with a registry using the --method flag to choose your auth method:

# Bearer token (default)
npx @getmcp/cli registry login my-team --method bearer

# Basic auth (username + password)
npx @getmcp/cli registry login my-team --method basic

# Custom header (key + value)
npx @getmcp/cli registry login my-team --method header

Logout

Remove stored credentials for a registry:

npx @getmcp/cli registry logout my-team

Environment variable override

For CI/CD pipelines or automated environments, set an environment variable instead of using interactive login. The variable GETMCP_REGISTRY_<NAME>_TOKEN is resolved first and treated as a bearer token:

# For a registry named "my-team"
export GETMCP_REGISTRY_MY_TEAM_TOKEN=your-token-here
npx @getmcp/cli add my-server --registry my-team

Credential storage

Credentials are stored locally at ~/.config/getmcp/credentials.json with 0600 permissions (owner read/write only). Removing a registry with registry remove automatically cleans up its credentials.

Server definitions are stored in a canonical format aligned with the official MCP registry schema. Config generators transform this into each app's native format — renaming fields, changing root keys, switching file formats.

Canonical Format
        |
+-------+-------+-------+-------+
|       |       |       |       |
Claude  VS Code Goose  Codex  + 15 more
Desktop (servers)(YAML) (TOML)   apps

There are two types of server configs:

• Stdio servers — run a local process with command, args, and env
• Remote servers — connect to a URL with url and optional transport (http, streamable-http, or sse)

Transport is auto-inferred: URLs ending in /sse default to SSE, others default to HTTP.

All packages are available on npm and can be used programmatically in your own projects.

import { generateConfig, generateAllConfigs } from "@getmcp/generators";

// Generate for a specific app
const config = generateConfig("goose", "github", {
  command: "npx",
  args: ["-y", "@modelcontextprotocol/server-github"],
  env: { GITHUB_TOKEN: "ghp_xxx" },
});
// => { extensions: { github: { cmd: "npx", args: [...], envs: {...} } } }

// Generate for ALL apps at once
const all = generateAllConfigs("github", {
  command: "npx",
  args: ["-y", "@modelcontextprotocol/server-github"],
  env: { GITHUB_TOKEN: "ghp_xxx" },
});

import { StdioServerConfig, CanonicalMCPConfig } from "@getmcp/core";

StdioServerConfig.parse({ command: "npx", args: ["server"] });
// throws ZodError if invalid

import { searchServers, getServersByCategory } from "@getmcp/registry";

searchServers("database");
// => [{ id: "io.github.modelcontextprotocol/server-postgres", slug: "postgres", ... }]

getServersByCategory("web");
// => [{ id: "io.github.anthropics/...", slug: "brave-search", ... }]

getmcp syncs server data from the official MCP registry. To add your MCP server, submit it to the official registry — getmcp will pick it up automatically during the next sync.

Once your server is in the official registry, it will appear in the web directory, CLI search, and all 19 config generators.