Registry Overview

The Registry feature lets you browse, search, and install MCP servers from one or more remote catalogs directly inside the TUI or programmatically via the registry client.

Quick Start

1. Add at least one registry to your config.yaml (see Configuring registries below).
2. Launch the TUI: argus-mcp tui
3. Press the key binding for Registry mode (shown in the footer).
4. The browser fetches the server list from your configured registries.
5. Use the search box to filter by name or description.
6. Select a server, review details in the right panel, and press Install.
7. The server definition is written to your config.yaml as a new backends entry and a hot-reload is triggered automatically.

Architecture Overview

┌──────────────────────────────────────────────────────────────────┐
│                       RegistryScreen                             │
│  ┌─────────────────────────┐  ┌────────────────────────────────┐ │
│  │  RegistryBrowserWidget  │  │      InstallPanelWidget        │ │
│  │  (searchable DataTable) │  │  (detail + Install button)     │ │
│  │                         │  │                                │ │
│  │  Name│Transport│Tools   │  │  Name: my-server               │ │
│  │  ────│─────────│─────   │  │  Transport: stdio              │ │
│  │  ... │  stdio  │  12    │  │  Command: uvx my-server        │ │
│  └─────────────────────────┘  │  Tools: list_files, read_...   │ │
│                               │                                │ │
│                               │  [Install]                     │ │
│                               └────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────┘
         │                          │
         ▼                          ▼
  RegistryClient ──────────── RegistryCache
    (httpx)          miss?     (~/.cache/argus-mcp/registry/)
         │
         ▼
  Registry API  (GET /v0/servers)
  (user-configured URL)

Module Map

Registry API

The client expects a REST endpoint that implements the /v0/servers contract described below. Any HTTP server returning the correct JSON shapes will work.

Endpoints

ServerEntry JSON Shape

{
  "name": "example-server",
  "description": "An example MCP server",
  "transport": "stdio",            // "stdio" | "sse" | "streamable-http"
  "command": "uvx example-server", // for stdio
  "args": ["--flag"],              // optional, for stdio
  "url": "",                       // for sse / streamable-http
  "version": "1.2.0",
  "icon_url": "",
  "categories": ["search", "coding"],
  "tools": [
    {
      "name": "list_files",
      "description": "List files in a directory",
      "inputSchema": { "type": "object", "properties": { } }
    }
  ]
}

ServerPage JSON Shape

{
  "servers": [ ... ],      // array of ServerEntry
  "next_cursor": "abc123", // null when no more pages
  "total": 42              // optional count
}

Configuring Registries

No registries are included by default. You must add the registries you want to use.

Option 1: config.yaml (recommended)

Add a registries section to your config.yaml:

registries:
  - name: community
    url: "https://glama.ai/api/mcp"
    priority: 100
    auth: none

  - name: smithery
    url: "https://registry.smithery.ai"
    priority: 200
    auth: none

  - name: internal
    url: "https://registry.corp.example.com/v0/servers"
    priority: 50
    auth: api-key
    api_key_env: INTERNAL_REGISTRY_KEY   # reads from environment variable

RegistryEntryConfig Fields

Option 2: TUI Settings

You can also manage registries from Settings > Registries in the TUI. These are persisted to the TUI's local settings.json file.

The TUI settings and config.yaml are merged at runtime. config.yaml registries are checked first, followed by TUI settings entries.

Resolution Order

1. TUI settings (settings.json) registries, sorted by priority
2. config.yaml registries section, sorted by priority
3. If neither has entries, the Registry screen shows a "No registries configured" message

Known Public Registries

The following registries are known to implement (or partially implement) the /v0/servers API contract. None of these are bundled or hardcoded -- add the ones you want to use in your config.yaml.

Installation Flow

When you press Install on a registry server:

1. ServerEntry.to_backend_config() converts the entry to a backend config dict matching Argus's config format:

   Transport	Generated Config
   stdio	{"type": "stdio", "command": "...", "args": [...]}
   sse	{"type": "sse", "url": "..."}
   streamable-http	{"type": "streamable-http", "url": "..."}

2. The config dict is written to config.yaml under backends.<server-name>.

3. A hot-reload is triggered via the management API, so the new backend starts connecting without a server restart.

Example

Installing a server called "mcp-github" with transport stdio adds:

backends:
  # ... existing backends ...
  mcp-github:
    type: stdio
    command: uvx mcp-github
    args: []

Management API Search

Argus exposes a server-side search endpoint through the management API that proxies queries to your configured registries. This is distinct from the external registry's own API.

GET /manage/v1/registry/search

Endpoint: GET /manage/v1/registry/search

Behavior: Searches configured registries in priority order, stopping at the first registry that returns results.

Example:

curl "http://localhost:9000/manage/v1/registry/search?q=github&limit=5"

Response:

{
  "servers": [
    {
      "name": "mcp-github",
      "description": "GitHub MCP server",
      "transport": "stdio",
      "command": "uvx mcp-github",
      "version": "1.0.0"
    }
  ],
  "registry": "community",
  "total": 1
}

Error responses:

Cache

API responses are cached to ~/.cache/argus-mcp/registry/ as JSON files (one per registry URL). The cache has a 300-second TTL -- after that, the next request re-fetches from the API. On network failure, the client transparently falls back to the cache.

To clear the cache manually:

rm -rf ~/.cache/argus-mcp/registry/

Running Your Own Registry

If you want to serve a private registry:

1. Build a compatible API -- any HTTP server that returns the JSON shapes above at GET /v0/servers will work. The client only requires:

   • GET /v0/servers (list/paginate)
   • GET /v0/servers/{name} (single entry)

2. Static file approach -- for a tiny catalog, serve a static servers.json:

   {
     "servers": [
       {
         "name": "my-internal-tool",
         "description": "Internal analysis tool",
         "transport": "stdio",
         "command": "uvx my-internal-tool",
         "version": "0.3.0",
         "tools": []
       }
     ],
     "total": 1
   }
   

   Host it behind nginx/caddy at https://internal.example.com/v0/servers.

3. Add it to your config:

   registries:
     - name: internal
       url: "https://internal.example.com"
       priority: 10
       auth: none