NimbleBrain MCP Registry

A curated registry of Model Context Protocol (MCP) servers optimized for the NimbleBrain runtime platform.

🌐 Live at: https://registry.nimbletools.ai

📚 API Docs: https://registry.nimbletools.ai/docs

Overview

This registry provides a REST API for discovering MCP servers, implementing a subset of the official MCP Registry API. While the official registry focuses on broad ecosystem support, this registry is specifically curated for servers that work well with the NimbleBrain platform.

Why This Registry?

• Curated Selection: Only includes servers tested and optimized for NimbleBrain's runtime
• Extended Metadata: Adds platform-specific configuration for health checks, resource limits, and deployment settings
• Container-Ready: All servers are packaged as OCI containers for seamless deployment
• API Compatibility: Implements the core MCP Registry API for easy integration

API Endpoints

The registry provides the following REST endpoints:

GET /                                    # API info and available endpoints
GET /v0/servers                         # List all servers
GET /v0/servers/{server_id}            # Get specific server details
GET /v0/servers/{server_id}/versions   # Get server versions
GET /schemas                           # List available schema versions
GET /schemas/latest/{filename}         # Get latest schema
GET /schemas/{version}/{filename}      # Get specific schema version
GET /health                            # Health check
GET /docs                              # Interactive API documentation (Swagger UI)

Base URL: https://registry.nimbletools.ai API Documentation: https://registry.nimbletools.ai/docs (Interactive Swagger UI)

Example API Calls

# List all servers
curl https://registry.nimbletools.ai/v0/servers

# Get specific server
curl https://registry.nimbletools.ai/v0/servers/ai.nimbletools%2Ffinnhub

# Check health
curl https://registry.nimbletools.ai/health

Server Schema

Our servers follow the MCP server schema with additional NimbleBrain-specific metadata:

{
  "$schema": "https://registry.nimbletools.ai/schemas/2025-09-22/nimbletools-server.schema.json",
  "name": "ai.nimbletools/example",
  "version": "1.0.0",
  "description": "Example MCP server",
  "packages": [{
    "registryType": "oci",
    "identifier": "nimbletools/example",
    "version": "1.0.0",
    "transport": { "type": "stdio" }
  }],
  "_meta": {
    "ai.nimbletools.mcp/v1": {
      "container": {
        "healthCheck": {
          "path": "/health",
          "port": 8000
        }
      },
      "resources": {
        "limits": { "memory": "256Mi", "cpu": "100m" }
      }
    }
  }
}

Deployment

This registry is automatically deployed to https://registry.nimbletools.ai via GitHub Actions on every push to the main branch.

Infrastructure

• Hosting: Fly.io
• Region: Global (auto-scaled)
• API: Fastify + Node.js 22
• CI/CD: GitHub Actions

Deployment Process

1. Push to main branch triggers CI/CD pipeline
2. Tests and type checking run
3. Docker image built and pushed to registry
4. Automatic deployment to Fly.io
5. Health checks verify deployment

Development

Prerequisites

• Node.js 22+
• Docker (for building server images)

Setup

# Install dependencies
npm install

# Run development server
npm run dev

# Validate all server definitions
npm run validate-servers

# Build for production
npm run build

# Run tests
npm test

# Run end-to-end tests
npm run test:e2e                    # Test all servers
npm run test:e2e -- --server=echo   # Test specific server

End-to-End Testing

The registry includes a comprehensive E2E testing framework that validates servers from deployment through MCP connectivity:

# Test all servers
npm run test:e2e

# Test a specific server
npm run test:e2e -- --server=echo

# Test against a different API endpoint
npm run test:e2e http://api.custom.dev

Test Fixtures: Each server can define custom tests in servers/{name}/test.json:

{
  "environment": {
    "API_KEY": "${API_KEY}"
  },
  "tests": [{
    "name": "Test description",
    "tool": "tool_name",
    "arguments": { "param": "value" },
    "expect": { "type": "text", "contains": "expected" }
  }]
}

Environment Variables: Create .env.e2e for secrets:

cp .env.e2e.example .env.e2e
# Edit .env.e2e with your API keys

The test runner automatically:

• Creates workspaces
• Sets secrets from fixtures
• Deploys servers
• Validates MCP connectivity
• Runs custom tool tests
• Cleans up resources

QA Environment Testing

For testing in QA/CI environments that use bearer token authentication instead of Clerk:

# Test all servers on default QA domain (qa.nimbletools.ai)
./e2e/test-qa.ts --token=YOUR_BEARER_TOKEN

# Test all servers on custom domain
./e2e/test-qa.ts --token=YOUR_BEARER_TOKEN --domain=qa.nimbletools.dev

# Test specific server
./e2e/test-qa.ts --token=YOUR_BEARER_TOKEN --server=echo

# Test with HTTP and custom port for local development
./e2e/test-qa.ts --token=YOUR_BEARER_TOKEN --domain=nt.dev --port=8080 --insecure

# Test with custom port on HTTPS
./e2e/test-qa.ts --token=YOUR_BEARER_TOKEN --domain=qa.nimbletools.ai --port=8443

# In CI/CD pipelines
./e2e/test-qa.ts --token=$QA_BEARER_TOKEN --domain=$QA_DOMAIN

The QA test script (test-qa.ts) provides the same functionality as the standard test script but:

• Uses bearer token authentication for all API requests
• Takes a base domain and automatically constructs API (api.<domain>) and MCP (mcp.<domain>) URLs
• Defaults to qa.nimbletools.ai domain
• Supports --insecure flag to use HTTP instead of HTTPS for local testing
• Supports --port flag to specify a custom port
• Suitable for automated CI/CD testing environments

Docker

# Build Docker image
docker build -t nimbletools-registry .

# Run container
docker run -p 8080:8080 nimbletools-registry

Contributing

See CONTRIBUTING.md for guidelines on adding new servers to the registry.

License

Apache 2.0 - See LICENSE file for details.