Skip to main content

Obot's Open Source Registry

Each Obot instance connects to our open source registry by default. You can follow this guide to add your MCP server to Obot's registry. You'll either submit just a catalog entry, or a catalog entry + a repackaged image (for containerized servers).

Step 0 — Pick your path​

Question: What type of MCP server are you shipping?

  • Remote HTTP (Hosted Service)

    You expose a hosted HTTP MCP endpoint at a fixed URL or domain.

    → You only need mcp-catalog.

  • Docker-based HTTP or Stdio npx/uvx

    You have a Docker image that serves HTTP MCP or you have a stdio npx/uvx MCP server.

    → You'll touch both repos: first mcp-images (to repackage it), then mcp-catalog.

⚠️ Not Currently Supported:

  • Docker images that use stdio transport (only HTTP-based Docker images are supported)
  • npx/uvx packages that serve streamable HTTP (only stdio-based npx/uvx packages are supported)

Step 1 — Repackage your image (Skip to Step 2 if you have a Remote HTTP server)​

If your server is containerized (Docker-based HTTP or stdio-based npx/uvx), we'll repackage and publish it first.

Fork from: https://github.com/obot-platform/mcp-images

Edit repackaging/images.yaml and add your entry:

Docker-based HTTP Servers​

- name: my-http-server
  type: docker
  package: ghcr.io/yourorg/mcp-http-server    # Your existing Docker image
  version: 1.0.0                              # Specific version tag

Node.js (npx) Servers​

- name: my-awesome-server
  type: node
  package: @myorg/mcp-awesome-server    # NPM package name
  version: 1.2.3                        # Specific version

Python (uvx) Servers​

- name: my-python-server
  type: python
  package: mcp-python-server            # PyPI package name
  version: 2.0.1

After Your Image is Published​

Once your PR in mcp-images merges, we'll publish:

ghcr.io/obot-platform/mcp-images/<your-server-name>:<version>

Then proceed to Step 2 and:

  • For Docker-based HTTP servers: use Option B with your published GHCR image
  • For stdio servers: use Option C with your published GHCR image

Step 2 — Create your catalog entry​

Fork from: https://github.com/obot-platform/mcp-catalog

Add a file: your-server-name.yaml

Base Template (required for all servers)​

name: Your Server Name
description: |
  One-line summary of what this server does.

  ## Features
  - Key capability 1 
  - Key capability 2 

  ## What you'll need to connect
  - API key from https://example.com/api-keys
  - Account with "read" scope enabled
  - (Optional) Optional

metadata:
  categories: category-a, category-b

icon: https://example.com/icon.png
repoURL: https://github.com/your-org/your-mcp-repo

# Environment variables your server needs (optional)
env:
  - key: API_KEY                     *# Actual env var name*
    name: API Key                    *# Display name in UI*
    required: true                   *# Is this mandatory?*
    sensitive: true                  *# Masks value in UI (for credentials)*
    description: Your API key from the developer dashboard

# Preview your server's tools
toolPreview:
  - name: search_documents
    description: Search through indexed documents using natural language
    params:
      query: Search query string
      limit: Maximum number of results (1-100)
  - name: get_document
    description: Retrieve a specific document by ID
    params:
      document_id: Unique identifier for the document

Tip: Generating Tool Previews

To easily generate your toolPreview section, connect your MCP server to an MCP client (like Claude Desktop, Cursor, or VSCode with MCP extension) and ask the AI to list all tools from your MCP server and convert the tool definitions to the tool preview format.

Now choose exactly one runtime block below.

Option A: Remote HTTP Server

Choose the case that matches your setup:

Case 1: Fixed Endpoint URL​

Use this when your server has one static URL for all users:

runtime: remote
remoteConfig:
  fixedURL: https://api.example.com/v1/mcp
  headers:
    - name: Personal Access Token
      description: PAT
      key: Authorization           # HTTP header name
      required: true
      sensitive: true

Case 2: Same Hostname, User Selects Path​

Use this when users connect to different paths on your domain:

runtime: remote
remoteConfig:
  hostname: api.example.com
  headers:
    - name: API Key
      description: Your API key from <https://example.com/settings>
      key: X-API-Key
      required: true
      sensitive: true

Users will specify their path when connecting (e.g., https://api.example.com/serviceA/mcp).

Case 3: URL Built from User Environment​

Use this when the URL includes user-specific values:

env:
  - key: WORKSPACE_URL
    name: Workspace URL
    description: "Your workspace URL, e.g., <https://mycompany.cloud.com>"
    required: true
    sensitive: false

runtime: remote
remoteConfig:
  URLTemplate: ${WORKSPACE_URL}/api/2.0/mcp/
  headers:
    - name: Personal Access Token
      description: PAT with workspace access
      key: Authorization
      required: true
      sensitive: true

Option B: Containerized HTTP Server

⚠️ Important: If you have a Docker image that serves HTTP MCP, you must complete Step 1 first to repackage your Docker image and wait for it to be published to GHCR. Then return here and use this runtime block:

runtime: containerized
containerizedConfig:
  image: ghcr.io/obot-platform/mcp-images/<your-server-name>:<tag>
  port: <port-number>           # Your container's exposed HTTP port
  path: /mcp           # HTTP path where MCP endpoint is served
  args:                # Optional runtime flags
    - flags # flags needed.

Requirements:

  • Your container must serve HTTP/SSE on the specified port
  • The MCP endpoint must be available at the specified path
Option C: Stdio MCP Server (npx, uvx)

⚠️ Important: If your server is stdio-based, you must complete Step 1 first to repackage your stdio server and wait for it to be published to GHCR. Then return here and use this runtime block:

runtime: containerized
containerizedConfig:
  image: ghcr.io/obot-platform/mcp-images/<your-server-name>:<tag>
  port: 8099         # Fixed for stdio servers
  path: /            # Fixed for stdio servers
  args:
    - <your-mcp-server-command>           # Command to run your stdio server
    # Add any additional flags your server needs:
    # - --region
    # - us-east-1

The args must include the command that starts your stdio server, plus any required flags.

Step 3 — Open your PR(s)​

For Remote HTTP Servers (Option A)​

Open one PR in mcp-catalog adding your-server-name.yaml (Step 2)

For Docker-based HTTP or Stdio Servers (Options B & C)​

  1. Open a PR in mcp-images editing repackaging/images.yaml (Step 1)
  2. Wait for the image to be published to GHCR (typically within a few hours after the PR is merged)
  3. Open a PR in mcp-catalog adding your-server-name.yaml referencing the published GHCR image (Step 2)

Pre-Submission Checklist​

Before opening your PR, verify:

  • description includes ## Features and ## What you'll need to connect sections
  • metadata.categories lists a few categories
  • icon is a square image, publicly accessible
  • repoURL points to GitHub (or documentation if unavailable)
  • toolPreview lists your tool schemas
  • Exactly one runtime block (remote OR containerized)
  • All env variables have clear descriptions
  • Sensitive credentials are marked sensitive: true
  • (Docker-based HTTP or Stdio only) Image is published to GHCR before catalog PR

Testing Your MCP Server Configuration​

Test with Obot running Locally​

If you have Obot running locally, you can test your catalog entry before submitting:

  1. When you run Obot locally, you'd need to set this env variable OBOT_SERVER_DEFAULT_MCPCATALOG_PATH to the absolute path of your local mcp-catalog fork.
  2. Add your YAML to your local Obot catalog directory
  3. On the MCP Servers page in the Admin UI, click sync
  4. Attempt to connect to your server through the UI
  5. Verify all tools appear and function correctly

Examples:​

Please refer to entries in https://github.com/obot-platform/mcp-catalog