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 into all detected AI apps
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 github

# 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

# 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.

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

{
  "servers": {
    "github": {},
    "postgres": {
      "env": {
        "DATABASE_URL": "postgresql://localhost:5432/mydb"
      }
    }
  }
}

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 the registry, merges any local overrides (like environment variables), and writes the correct config for every detected app.

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

Canonical Format (FastMCP-aligned)
        |
+-------+-------+-------+-------+
|       |       |       |       |
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: "postgres", ... }]

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

Want to add your MCP server to the getmcp registry? Here's how:

1. Create a new JSON file at packages/registry/servers/your-server.json
2. Add a $schema field for IDE autocompletion
3. Define your server's metadata and config
4. Run the tests to validate your entry (the registry auto-discovers all JSON files)

Here's an example registry entry:

{
  "$schema": "https://getmcp.es/registry-entry.schema.json",
  "id": "my-server",
  "name": "My Server",
  "description": "What your server does",
  "categories": ["productivity"],
  "author": "your-name",
  "runtime": "node",
  "package": "@scope/my-mcp-server",
  "repository": "https://github.com/you/my-mcp-server",
  "requiredEnvVars": ["MY_API_KEY"],
  "config": {
    "command": "npx",
    "args": ["-y", "@scope/my-mcp-server"],
    "env": { "MY_API_KEY": "" }
  }
}

Once added, your server will automatically appear in the web directory, CLI search, and all 19 config generators. Open a pull request on GitHub to submit your server.