Quick Start

Quick Start

This guide walks you through the full mcpfleet workflow: start a registry, log in, push your server definitions, and apply them to an AI coding agent.

You need the mcpfleet CLI on your PATH (see Installation).

1. Start the Registry

The registry stores your server definitions. Run it with Docker Compose:

git clone https://github.com/mcpfleet/mcpfleet-registry.git
cd mcpfleet-registry
docker compose up -d

Or run it with Go. The SQLite driver needs cgo, so you also need a C compiler and the SQLite headers (for example gcc and libsqlite3-dev):

git clone https://github.com/mcpfleet/mcpfleet-registry.git
cd mcpfleet-registry
CGO_ENABLED=1 go run ./cmd/registry

Either way, the registry listens on http://localhost:8080.

2. Create Your First Token

A fresh registry has no tokens. Create the first one with the bootstrap endpoint:

curl -X POST http://localhost:8080/bootstrap \
  -H 'Content-Type: application/json' \
  -d '{"name": "admin"}'

The response holds your token:

{"$schema":"...","id":"...","name":"admin","token":"mcp_...","created_at":"..."}

Save the token value now: the registry shows it only once. The bootstrap endpoint works only once per registry; later tokens come from an existing token or, if you lose them all, from Recover access.

3. Log In

Point the CLI at your registry and give it the token:

mcpfleet auth login --url http://localhost:8080 --token mcp_...

The CLI saves the token and the registry URL under ~/.config/mcpfleet/, so later commands use them. Run mcpfleet auth login without flags to enter both in an interactive form instead.

4. Define Your Servers

Describe your MCP servers in a YAML file. The file is a list of server definitions:

servers.yaml

- name: filesystem
  description: Read and write files in my projects
  transport: stdio
  install:
    type: npx
    package: "@modelcontextprotocol/server-filesystem"
  command: npx
  # replace the last argument with a directory the server may access
  args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/me/projects"]
  tags: [dev]

- name: fetch
  description: Fetch web pages as Markdown
  transport: stdio
  install:
    type: uvx
    package: mcp-server-fetch
  command: uvx
  args: ["mcp-server-fetch"]
  env:
    LOG_LEVEL:
      value: info
  tags: [web]

Each server needs a name and, for a local stdio server like these, a command; a remote sse or http server has a url instead (see mcpfleet push). env maps each variable to an object with either a value (a literal) or a secret (the name of a secret in your local mcpfleet vault, resolved when you apply).

5. Push Them to the Registry

mcpfleet push servers.yaml

created  filesystem
created  fetch

Pushing the same file again updates the existing servers (updated filesystem).

6. List Your Servers

mcpfleet list

MCP Servers

NAME        TRANSPORT  TARGET
----        ---------  ------
fetch       stdio      uvx mcp-server-fetch
filesystem  stdio      npx -y @modelcontextprotocol/server-filesystem /home/me/projects

7. Store the Secret

A server that needs a token references a secret by name instead of holding the value, for example:

- name: github
  command: npx
  args: ["-y", "@modelcontextprotocol/server-github"]
  env:
    GITHUB_TOKEN:
      secret: github_token

Store the value in your local vault before you apply. The prompt does not show what you type:

mcpfleet secret set github_token

✓ Saved secret github_token

In a script, pipe the value in with --stdin. mcpfleet secret list shows the stored names. If a server references a secret that is not in the vault, apply stops with an error naming it and changes nothing. The servers in servers.yaml above use no secrets, so you can skip this step for them.

8. Apply Them to an Agent

Write every server from the registry into Cursor’s config:

mcpfleet apply cursor

✓ Applied 2 MCP server(s) to cursor

To apply only some servers, filter by tag (repeat --tag for more than one):

mcpfleet apply --tag dev cursor

apply adds or updates the mcpfleet servers in the agent’s config and leaves your other entries alone. Supported agents: claude-code, claude-desktop, crush, cursor, windsurf, zed.

9. Verify

Check that Cursor’s MCP configuration was updated:

cat ~/.cursor/mcp.json

{
  "mcpServers": {
    "fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"],
      "env": { "LOG_LEVEL": "info" }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/me/projects"]
    }
  }
}

10. Back Up Your Definitions

Pull everything from the registry into a YAML file in the same format as servers.yaml:

mcpfleet pull backup.yaml

pulled 2 server(s) -> backup.yaml

What’s Next?

• CLI Reference for all available commands
• Installation for other ways to install the CLI and run the registry