> For the complete documentation index, see [llms.txt](https://mcp.avelino.run/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://mcp.avelino.run/guides/registry.md).

# Registry

The [MCP server registry](https://registry.modelcontextprotocol.io) is a public directory of MCP servers. `mcp` can search it and add servers directly from it.

## Searching

```bash
mcp search filesystem
```

```json
[
  {
    "name": "filesystem",
    "description": "MCP server for file system operations",
    "repository": "https://github.com/anthropics/mcp-servers",
    "install": ["npx @anthropic/fs-mcp-server"]
  }
]
```

Search with multiple words:

```bash
mcp search "database sql"
```

Results include:

* **name** — Server identifier (used with `mcp add`)
* **description** — What the server does
* **repository** — Source code link
* **install** — How to install/run (runtime + package)

## Adding from registry

```bash
mcp add filesystem
```

What happens:

1. Searches the registry for a server named `filesystem`
2. Reads the server metadata (command, args, env vars)
3. Generates a config entry in `~/.config/mcp/servers.json`
4. Prints which environment variables you need to set

```
✓ Server "filesystem" added to /home/you/.config/mcp/servers.json

Configure the following environment variables:
  ALLOWED_PATHS  — Directories the server can access

Run to test:
  mcp filesystem --list
```

### What gets generated

For a package-based server (most common), the config looks like:

```json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@anthropic/fs-mcp-server"],
      "env": {
        "ALLOWED_PATHS": "${ALLOWED_PATHS}"
      }
    }
  }
}
```

For a remote server with HTTP transport:

```json
{
  "mcpServers": {
    "remote-service": {
      "url": "https://example.com/mcp/sse"
    }
  }
}
```

The registry entry determines which type is used. Packages (stdio) take priority over remotes (HTTP).

## Already exists?

If you try to add a server that's already in your config:

```bash
mcp add filesystem
```

```
error: server "filesystem" already exists in config
```

Remove it first if you want to re-add:

```bash
mcp remove filesystem
mcp add filesystem
```

> If you only want to pull fresh metadata from the registry (new package version, new env vars, updated args), use `mcp update <name>` instead — it preserves your customizations (filled env values, headers, idle\_timeout, etc.). See [`mcp update`](/reference/cli.md#mcp-update-name).

## Manual HTTP servers

For servers not in the registry, add them manually:

```bash
mcp add --url https://mcp.example.com/sse my-server
```

This creates a minimal HTTP entry:

```json
{
  "mcpServers": {
    "my-server": {
      "url": "https://mcp.example.com/sse"
    }
  }
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://mcp.avelino.run/guides/registry.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.