> For the complete documentation index, see [llms.txt](https://gotts.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gotts.gitbook.io/docs/gotts-safe-mcp-server/mcp-server/16-registries.md).

# Ecosystem Listings

> **Document Type**: OPS (informative) | **Package**: `packages/safe/` | **Prerequisites**: [13-distribution.md](/docs/gotts-safe-mcp-server/mcp-server/13-distribution.md) | **Last Updated**: 2026-02-18
>
> How to get the server listed on every major MCP registry, directory, and distribution channel. Covers the official MCP Registry, Smithery, Docker MCP Catalog, and community directories. Includes one-click install integration and npm distribution tag strategy. This is an operational document — see [shared/doc-standards.md](/docs/prd-shared/doc-standards.md) for document type definitions.

***

## Overview

Distribution is a multiplier on technical quality. A well-built MCP server that nobody can find converts to zero adoption. The MCP ecosystem has converged on four primary distribution channels that cover distinct audiences:

| Channel                   | Audience               | Install Method              | Priority                               |
| ------------------------- | ---------------------- | --------------------------- | -------------------------------------- |
| **Official MCP Registry** | All MCP clients        | `mcp-publisher publish`     | P0 — required for `mcpName` validation |
| **Smithery**              | Developers, CLI users  | `npx @smithery/cli install` | P0 — largest active registry           |
| **npm**                   | Node.js ecosystem      | `npx -y @gotts.ai/safe`     | P0 — primary distribution              |
| **Docker MCP Catalog**    | Container-native users | Docker Desktop one-click    | P1 — growing fast                      |
| **mcp.so / PulseMCP**     | Discovery, SEO         | GitHub URL submission       | P2 — low maintenance                   |

> **Two npm packages**: `@gotts.ai/safe` is the standalone MCP server (what registries list). `@gotts.ai` is the unified CLI (`gotts setup`, `gotts safe`, `gotts portal`, etc.) for developer convenience. All registry entries and MCP client configs should use `@gotts.ai/safe` for faster cold-start and single-purpose clarity.

Submit to all channels before the first public release. Each has a different format but manageable overlap.

***

## 1. npm Package Requirements

Before any registry submission, the npm packages must meet these requirements. Two packages are published to npm:

* **`@gotts.ai/safe`** — Standalone MCP server. This is what MCP registries and client configs should point to (faster cold-start, single-purpose).
* **`@gotts.ai`** — Unified CLI wrapping all Gotts tools (`gotts setup`, `gotts safe`, `gotts devenv`, `gotts portal`, etc.). For interactive developer use, not for MCP client configs.

MCP registries should list `@gotts.ai/safe`, not `@gotts.ai`. The unified CLI is a convenience wrapper for developers, not a registry entry.

### Required `package.json` Fields — `@gotts.ai/safe`

```json
{
  "name": "@gotts.ai/safe",
  "version": "1.0.0",
  "description": "Official Gotts Safe for AI agents — pool data, swaps, liquidity, vaults across all chains",
  "type": "module",
  "main": "dist/index.js",
  "bin": {
    "gotts-safe": "./dist/index.js"
  },
  "files": [
    "dist",
    "README.md",
    "INSTALL.md",
    "CHANGELOG.md",
    "LICENSE",
    ".env.example"
  ],
  "keywords": [
    "mcp",
    "model-context-protocol",
    "uniswap",
    "defi",
    "ai-agent",
    "claude",
    "cursor",
    "llm",
    "erc-4626",
    "base",
    "ethereum",
    "web3",
    "liquidity",
    "trading",
    "vault",
    "agent-economy"
  ],
  "mcpName": "io.github.gotts-protocol/mcp-server",
  "engines": { "node": ">=20.0.0" },
  "scripts": {
    "build": "tsup",
    "start": "node dist/index.js",
    "dev": "tsx src/index.ts",
    "prepublishOnly": "pnpm build",
    "health": "node dist/index.js --health",
    "inspect": "npx @modelcontextprotocol/inspector node dist/index.js"
  }
}
```

### Required `package.json` Fields — `@gotts.ai` (Unified CLI)

```json
{
  "name": "@gotts.ai",
  "version": "1.0.0",
  "description": "Gotts — Agent Capital Markets powered by Uniswap. Unified CLI for setup, MCP server, devenv, portal, and more.",
  "type": "module",
  "bin": {
    "gotts": "./dist/cli.js"
  },
  "files": ["dist", "README.md", "LICENSE"],
  "keywords": [
    "gotts",
    "uniswap",
    "defi",
    "ai-agent",
    "mcp",
    "model-context-protocol",
    "cli",
    "agent-economy",
    "erc-4626",
    "erc-8004"
  ],
  "engines": { "node": ">=20.0.0" }
}
```

> **Note**: The `@gotts.ai` package does NOT have an `mcpName` field because it is not an MCP server — it is a CLI that wraps one. Registry listings use `@gotts.ai/safe`.

**Critical fields explained:**

* **`bin`**: Mandatory for `npx` zero-install execution. The value must point to a file with a `#!/usr/bin/env node` shebang at line 1. Without this, `npx @gotts.ai/safe` (or `npx @gotts.ai`) fails.
* **`mcpName`**: The `io.github.{org}/{repo}` format is **required** for official MCP Registry validation (on `@gotts.ai/safe` only). Use GitHub namespace authentication. This field is validated when `mcp-publisher publish server.json` is run.
* **`files`**: Include `.env.example` so it ships with the package. Users can `npx @gotts.ai/safe && cat .env.example` immediately.
* **`keywords`**: Both MCP ecosystem terms (`mcp`, `model-context-protocol`) and DeFi search terms (`uniswap`, `defi`, `ethereum`). This determines discoverability on npm and secondary registries.
* **`engines`**: Node 20+ minimum. State this explicitly — many install issues stem from Node version mismatches. Consider adding an `.nvmrc` file.

### SemVer with MCP-Specific Semantics

Because MCP tool schemas are public contracts consumed by LLMs, the standard semver semantics have MCP-specific nuances:

| Change Type                                  | Version Bump                      | Reason                                |
| -------------------------------------------- | --------------------------------- | ------------------------------------- |
| Add new tool                                 | **MINOR**                         | Additive, backward compatible         |
| Remove or rename a tool                      | **MAJOR**                         | Breaks agents that depend on the tool |
| Change a parameter name or type              | **MAJOR**                         | Breaks tool invocations               |
| Add optional parameter with default          | **MINOR**                         | Backward compatible                   |
| Fix tool description / documentation         | **PATCH**                         | No schema change                      |
| Fix a bug in tool implementation             | **PATCH**                         | No schema change                      |
| Change `serverInfo.version` in MCP handshake | Must match `package.json` version | —                                     |

**The `serverInfo.version` in the MCP handshake must always match `package.json`.** Clients cache tool lists by server name+version — a mismatch causes stale tool descriptions.

### npm Distribution Tags

Use npm distribution tags to separate stable, preview, and development builds. Both `@gotts.ai/safe` and `@gotts.ai` follow the same tagging scheme:

```bash
# Publish stable release (users should pin to this)
npm publish --tag latest

# Publish preview of upcoming features
npm publish --tag beta

# Publish latest main branch build (CI/CD, bleeding edge)
npm publish --tag dev
```

All example configs in docs use `@latest`:

```json
// MCP client configs (direct — recommended):
"args": ["-y", "@gotts.ai/safe@latest"]

// Via unified CLI:
"args": ["-y", "@gotts.ai@latest", "safe"]
```

Advanced users can pin a specific version: `@gotts.ai/safe@1.2.0`. Document both in `INSTALL.md`.

> **Version coordination**: `@gotts.ai` and `@gotts.ai/safe` are versioned independently. The unified CLI declares `@gotts.ai/safe` as an optional peer dependency with a compatible version range.

### `CHANGELOG.md` Format

Maintain a `CHANGELOG.md` following the [Keep a Changelog](https://keepachangelog.com) format. Every release entry must include:

* **Added** — new tools, new parameters, new profiles
* **Changed** — modified tool behavior or descriptions (MINOR)
* **Deprecated** — tools that will be removed in the next major version
* **Removed** — tools that were removed (MAJOR, migration instructions required)
* **Fixed** — bug fixes
* **Security** — security-related fixes

```markdown
## [1.1.0] — 2026-03-01

### Added

- `get_trending_pools` — Returns top pools by 24h volume across all chains
- `data` profile now includes CoinGecko price data via x402

### Fixed

- `get_token_price` now handles tokens with no liquidity gracefully

## [1.0.0] — 2026-02-18

### Added

- Initial release with 27 tools across data, trader, lp, vault, and fees profiles
```

***

## 2. Official MCP Registry

**URL**: [registry.modelcontextprotocol.io](https://registry.modelcontextprotocol.io) **Launched**: September 2025 (API v0.1 frozen October 2025) **Backed by**: Anthropic, GitHub, Microsoft, PulseMCP

The official registry is a **metaregistry** — it hosts metadata pointing to npm, PyPI, Docker Hub, etc., not the code itself. Being listed here is what enables `mcpName` validation and first-party discoverability in Claude, VS Code, and other Anthropic/Microsoft products.

### `server.json` Format

Create `server.json` at the repo root:

```json
{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
  "name": "io.github.gotts-protocol/mcp-server",
  "title": "Gotts Safe",
  "description": "Official Gotts Safe for AI agents — pool data, swaps, liquidity provision, vault management, and protocol fee tooling across all 11 Uniswap-deployed chains.",
  "version": "1.0.0",
  "websiteUrl": "https://docs.agenticvaults.xyz",
  "repository": {
    "url": "https://github.com/gotts-protocol/mcp-server",
    "source": "github"
  },
  "packages": [
    {
      "registryType": "npm",
      "registryBaseUrl": "https://registry.npmjs.org",
      "identifier": "@gotts.ai/safe",
      "version": "1.0.0",
      "transport": { "type": "stdio" },
      "environmentVariables": [
        {
          "name": "GOTTS_PROFILE",
          "description": "Tool profile: data (read-only), trader, lp, vault, fees, full",
          "required": false,
          "isSecret": false
        },
        {
          "name": "GOTTS_PRIVY_APP_ID",
          "description": "Privy App ID for server wallet (required for write operations)",
          "required": false,
          "isSecret": false
        },
        {
          "name": "GOTTS_PRIVY_APP_SECRET",
          "description": "Privy App Secret for server wallet",
          "required": false,
          "isSecret": true
        },
        {
          "name": "GOTTS_WALLET_PRIVATE_KEY",
          "description": "Local wallet private key (dev only — use Privy for production)",
          "required": false,
          "isSecret": true
        }
      ]
    }
  ],
  "remotes": [
    {
      "type": "http",
      "url": "https://mcp.agenticvaults.xyz/mcp",
      "description": "Hosted read-only endpoint (no wallet required)"
    }
  ]
}
```

> **Registry package**: The `server.json` lists `@gotts.ai/safe` as the npm package, not `@gotts.ai`. The official MCP Registry indexes MCP servers, and `@gotts.ai/safe` is the server. The unified CLI (`@gotts.ai`) wraps it but is not itself an MCP server.

### Publishing Workflow

```bash
# 1. Initialize server.json (first time only — generates template)
npx mcp-publisher init

# 2. Publish npm package
npm publish --access public

# 3. Authenticate via GitHub OAuth
npx mcp-publisher login github

# 4. Publish to registry (validates mcpName namespace against GitHub auth)
npx mcp-publisher publish server.json

# 5. Verify listing
npx mcp-publisher status io.github.gotts-protocol/mcp-server
```

**Namespace authentication**: The `io.github.{org}` prefix is validated against GitHub OAuth. You must authenticate as a member of the `gotts-protocol` GitHub organization. Alternative: DNS TXT verification for custom domains (e.g., `io.agenticvaults`).

***

## 3. Smithery

**URL**: [smithery.ai](https://smithery.ai) **Scale**: 7,300+ servers listed, CLI install support, auto-generated install guides per client

Smithery is the most active community registry. Being listed here enables:

* `npx @smithery/cli install @gotts.ai/safe --client claude`
* Auto-generated install instructions for every supported MCP client
* Discovery by developers searching "uniswap" or "defi"
* Smithery's hosted deployment for remote access (they build and run the server)

> **Registry listing**: List `@gotts.ai/safe` on Smithery (the MCP server), not `@gotts.ai` (the CLI wrapper). Smithery expects a server that speaks MCP stdio, which `@gotts.ai/safe` does directly. The unified CLI (`@gotts.ai`) is documented in the README as an alternative install path.

### `smithery.yaml` Format

Create `smithery.yaml` at the repo root:

```yaml
name: Gotts Safe
description: >
  Official Gotts Safe for AI agents. Covers pool data, token prices,
  swap execution, liquidity management, vault operations, and protocol fee tooling
  across all 11 Uniswap-deployed chains (Ethereum, Base, Arbitrum, Optimism, Polygon,
  and more).
version: 1.0.0
author: gotts-protocol
license: MIT
homepage: https://agenticvaults.xyz
repository: https://github.com/gotts-protocol/mcp-server
tags:
  - uniswap
  - defi
  - ethereum
  - base
  - trading
  - liquidity
  - vault
  - agent-economy

startCommand:
  type: stdio
  command: npx
  args:
    - "-y"
    - "@gotts.ai/safe@latest"
  configSchema:
    type: object
    properties:
      GOTTS_PROFILE:
        type: string
        default: data
        enum: [data, trader, lp, fees, vault, full]
        description: "Tool profile to activate (start with 'data' — no wallet needed)"
      GOTTS_WALLET_PRIVATE_KEY:
        type: string
        description: "Local wallet private key (dev only — use Privy for production)"
        secret: true
      GOTTS_PRIVY_APP_ID:
        type: string
        description: "Privy App ID for TEE-backed server wallet"
      GOTTS_PRIVY_APP_SECRET:
        type: string
        description: "Privy App Secret"
        secret: true
    required: []
```

**Submission**: Smithery auto-indexes public GitHub repos with a `smithery.yaml`. No manual submission required — just merge the file to main. Within 24 hours of publish, the server appears in the Smithery catalog.

***

## 4. Docker MCP Catalog

**URL**: [hub.docker.com/u/mcp](https://hub.docker.com/u/mcp) **Scale**: 270+ curated servers, Docker Desktop GUI, Docker MCP Toolkit integration

Docker provides sandboxed execution with resource limits (1 CPU, 2GB memory, no host filesystem access by default). This is particularly valuable for a crypto server — containers isolate the wallet from the host filesystem and network.

### Docker Image

Build and publish the official image:

```dockerfile
# Dockerfile
FROM node:22-slim AS builder
WORKDIR /app
COPY package.json pnpm-lock.yaml ./
RUN pnpm install --frozen-lockfile
COPY src/ ./src/
COPY tsup.config.ts tsconfig.json ./
RUN pnpm build

FROM node:22-slim
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY package.json .env.example ./
RUN chmod +x dist/index.js
ENV NODE_ENV=production
HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
  CMD node dist/index.js --health || exit 1
ENTRYPOINT ["node", "dist/index.js"]
```

```bash
# Build and push
docker build -t gottsprotocol/safe:latest .
docker push gottsprotocol/safe:latest

# MCP client config using Docker
# (note: -i flag required for stdio transport)
```

MCP client config:

```json
{
  "mcpServers": {
    "uniswap": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--env-file",
        "~/.gotts-protocol/.env",
        "gottsprotocol/safe:latest"
      ]
    }
  }
}
```

### Docker MCP Catalog Submission

Submit via PR to [github.com/docker/mcp-registry](https://github.com/docker/mcp-registry):

```yaml
# server.yaml (in the PR)
name: gotts-safe
type: server
meta:
  category: finance
  tags:
    - defi
    - crypto
    - uniswap
    - vault
    - liquidity
    - trading
about:
  title: Gotts Safe
  description: >
    Official Gotts Safe for AI agents. Pool data, swaps, liquidity,
    vault operations, and protocol fee tooling across all Uniswap-deployed chains.
env:
  - name: GOTTS_PROFILE
    description: "Tool profile: data (read-only, no wallet needed), trader, lp, fees, vault, full"
    required: false
    secret: false
  - name: GOTTS_WALLET_PRIVATE_KEY
    description: "Local wallet private key (dev only)"
    required: false
    secret: true
  - name: GOTTS_PRIVY_APP_ID
    description: "Privy App ID (production wallets)"
    required: false
    secret: false
  - name: GOTTS_PRIVY_APP_SECRET
    description: "Privy App Secret"
    required: false
    secret: true
```

**Submission requirements**: MIT or Apache 2.0 license, Dockerfile at repo root, PR to docker/mcp-registry. Docker builds, signs, and publishes the image to the `mcp/` namespace on Docker Hub. Available in Docker Desktop within 24 hours of approval.

**Benefits of Docker distribution**:

* Docker Desktop GUI: users discover, configure, and connect without touching config files
* SBOM (Software Bill of Materials) generated automatically
* Image signing via Docker Content Trust
* `docker mcp server enable agenticuniswap` one-command enable

***

## 5. Community Directories

These directories require minimal maintenance (usually just a GitHub URL) but expand discoverability and SEO.

| Directory               | URL                                     | Submission Method    | Audience                                |
| ----------------------- | --------------------------------------- | -------------------- | --------------------------------------- |
| **mcp.so**              | mcp.so                                  | GitHub issue or form | 17,600+ servers listed                  |
| **PulseMCP**            | pulsemcp.com                            | GitHub PR            | 8,380+ servers, Anthropic-adjacent      |
| **Awesome MCP Servers** | github.com/punkpeye/awesome-mcp-servers | GitHub PR            | Curated list, high developer visibility |
| **claudemcp.com**       | claudemcp.com                           | Submission form      | Claude-focused discovery                |
| **mcpmarket.com**       | mcpmarket.com                           | GitHub URL           | General MCP marketplace                 |

**Submission order**: Official Registry → Smithery (auto-indexed) → Docker MCP Catalog → mcp.so → PulseMCP → Awesome MCP Servers.

Submit to mcp.so and PulseMCP by opening a GitHub issue/PR with the server name, description, npm package URL, and a one-line description of what makes it unique.

***

## 6. One-Click Install Integration

One-click install buttons dramatically reduce friction for new users. Add these to the README and docs.

### Cursor Deeplink

Cursor supports deeplink-based MCP server installation since Cursor 1.0. The config is base64-encoded JSON:

```markdown
[![Install in Cursor](https://cursor.sh/deeplink/badge.svg)](cursor://anysphere.cursor-deeplink/mcp/install?name=uniswap&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBhZ2VudGljLXVuaXN3YXAvbWNwLXNlcnZlckBsYXRlc3QiXSwiZW52Ijp7IlVOSVNXQVBfTUNQX1BST0ZJTEUiOiJkYXRhIn19)
```

The base64 payload decodes to:

```json
{
  "command": "npx",
  "args": ["-y", "@gotts.ai/safe@latest"],
  "env": { "GOTTS_PROFILE": "data" }
}
```

Generate profile-specific deeplinks:

```typescript
function cursorDeeplink(
  profile: string,
  extraEnv: Record<string, string> = {},
): string {
  const config = {
    command: "npx",
    args: ["-y", "@gotts.ai/safe@latest"],
    env: { GOTTS_PROFILE: profile, ...extraEnv },
  };
  const encoded = Buffer.from(JSON.stringify(config)).toString("base64");
  return `cursor://anysphere.cursor-deeplink/mcp/install?name=uniswap-${profile}&config=${encoded}`;
}
```

### VS Code Install URL

VS Code supports a similar pattern for MCP server installation:

```
vscode:mcp/install?%7B%22name%22%3A%22uniswap%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40gotts-protocol%2Fmcp-server%40latest%22%5D%7D
```

The URL-decoded JSON:

```json
{
  "name": "uniswap",
  "command": "npx",
  "args": ["-y", "@gotts.ai/safe@latest"]
}
```

### Claude Code CLI

```bash
# One-liner — adds to user's global MCP config (direct, recommended):
claude mcp add uniswap -- npx -y @gotts.ai/safe@latest

# With profile:
claude mcp add uniswap-trader -- npx -y @gotts.ai/safe@latest --env GOTTS_PROFILE=trader

# Via unified CLI (alternative):
claude mcp add uniswap -- npx -y @gotts.ai@latest safe
```

### Gotts CLI Install-MCP

The unified CLI includes a built-in `install-mcp` subcommand that auto-detects installed MCP clients and writes the config:

```bash
# Interactive — detects Claude Desktop, Cursor, VS Code, etc.:
npx @gotts.ai install-mcp

# Non-interactive:
npx @gotts.ai install-mcp --client claude --profile data
```

This replaces `npx @gotts.ai/create` for MCP config injection. The `gotts setup` command (full interactive wizard) also includes MCP config installation as part of its flow.

Document all install methods in the README under a "Quick Install" section with copy-paste badges.

***

## 7. Hosted Read-Only Endpoint

Deploy a public read-only endpoint that requires no wallet and no API key. This is the zero-friction first-touch experience.

**URL**: `https://mcp.agenticvaults.xyz/mcp` (Streamable HTTP, read-only tools only)

**Client config** (for clients supporting HTTP transport natively):

```json
{
  "mcpServers": {
    "uniswap": {
      "type": "http",
      "url": "https://mcp.agenticvaults.xyz/mcp"
    }
  }
}
```

**For Claude Desktop** (which doesn't support `type: "http"` in JSON config directly — use the Connectors UI or `mcp-remote` bridge):

```json
{
  "mcpServers": {
    "uniswap-remote": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.agenticvaults.xyz/mcp"]
    }
  }
}
```

**Security constraint**: The hosted endpoint exposes **only read-only tools** (the `data` profile). No wallet operations. No private keys anywhere in the hosted infrastructure. Write operations require local stdio deployment with a locally-held wallet credential.

This maps to the "transaction-crafter" model (agent prepares unsigned transactions for user wallet signing) — safe for remote hosting. The "agent-controlled" model (agent holds signing keys) must remain local.

**Hosting**: Cloudflare Workers (free tier: 100K requests/day, paid $5/month: 10M requests). Stateless `createMcpHandler` pattern — no Durable Objects needed for read-only tools. See [14-deployment.md](/docs/gotts-safe-mcp-server/mcp-server/14-deployment.md) for deployment details.

***

## 8. Smithery CLI Install Experience

When a user installs via Smithery CLI, this is the flow:

```bash
npx @smithery/cli install @gotts.ai/safe --client claude

# Output:
# ✅ Found @gotts.ai/safe on Smithery
#
# Configuring for Claude Desktop...
#
# GOTTS_PROFILE (Tool profile):
#   1. data (read-only, no wallet needed) ← default
#   2. trader
#   3. lp
#   4. fees
#   5. vault
#   6. full
#
# Select profile [1]:
#
# ✅ Added to ~/Library/Application Support/Claude/claude_desktop_config.json
# ✅ Restart Claude Desktop to activate.
```

The `configSchema` in `smithery.yaml` drives this prompt sequence. Keep the schema minimal — only the fields users need to decide at install time. Everything else should have sensible defaults.

***

## Milestone

Registry submission is part of Phase 1 launch:

* Before public v1.0 release: `@gotts.ai/safe` and `@gotts.ai` published to npm + official registry + Smithery yaml merged
* Week of v1.0 release: Docker MCP Catalog PR submitted
* Week after v1.0: mcp.so, PulseMCP, Awesome MCP Servers submissions
* One-click deeplinks live in README on release day
* `npx @gotts.ai setup` (unified CLI) operational as the primary onboarding path

See [12-milestones.md](/docs/gotts-safe-mcp-server/mcp-server/12-milestones.md) for full milestone context.