# ToolSDK MCP Registry — Private Gateway + Sandbox

> Self-host a private MCP gateway/registry with OpenAPI, sandboxed remote execution and OAuth 2.1, or use @toolsdk.ai/registry to query server configs.

## Install

Merge the JSON below into your `.mcp.json`:

## Quick Use

1. Start the self-hosted registry (defaults):
   ```bash
   docker compose up -d
   ```
2. Open the UI and docs:
   - Web UI: http://localhost:3003
   - Swagger: http://localhost:3003/swagger
3. Run a tool remotely (example):
   ```bash
   curl -X POST http://localhost:3003/api/v1/packages/run \
     -H "Content-Type: application/json" \
     -d '{"packageName":"@modelcontextprotocol/server-everything","toolKey":"echo","inputData":{"message":"hello"},"envs":{}}'
   ```

## Intro

Self-host a private MCP gateway/registry with OpenAPI, sandboxed remote execution and OAuth 2.1, or use @toolsdk.ai/registry to query server configs.

- **Best for:** teams that need a searchable MCP catalog plus a safe, auditable execution gateway
- **Works with:** Docker; MCP servers (stdio + Streamable HTTP); any HTTP client; OpenAPI/Swagger
- **Setup time:** 10–20 minutes

## Practical Notes

- Quant: the README states the registry ships metadata for **4,547+** public MCP servers.
- Quant: default local endpoints are **http://localhost:3003** (UI + Swagger) for quick validation.

## How to adopt it without creating a new failure mode

Treat the registry as *infrastructure*, not a list:

1. **Decide your trust boundary.** Keep a small allow-list of packages for production (prune `packages/` for private deployments).
2. **Separate discovery from execution.** Let anyone search, but restrict `run`/remote execution to controlled environments.
3. **Standardize env injection.** For secrets, prefer per-tool env mapping and short-lived tokens; review `x-mcp-env-*` usage.

## Suggested rollout checklist

- Start with 5–10 tools your team already uses (GitHub, docs fetch, DB read-only) and validate each end-to-end.
- Add monitoring around run volume and error rates; treat a spike as a policy regression.
- If you expose Streamable HTTP gateways externally, add auth + rate limits first.

### FAQ

**Q: Is this just a list of MCP servers?**
A: No. It includes a self-hosted gateway with search + remote execution and OpenAPI docs.

**Q: Can I run STDIO-only servers remotely?**
A: The README describes exposing registered packages behind a Streamable HTTP proxy endpoint.

**Q: How do I keep it safe?**
A: Use allow-lists, limit env injection, and restrict remote execution to controlled environments.

## Source & Thanks

> Source: https://github.com/toolsdk-ai/toolsdk-mcp-registry
> License: MIT
> GitHub stars: 172 · forks: 84

---

<!-- ZH -->

## 快速使用

1. 一键启动（默认配置）：
   ```bash
   docker compose up -d
   ```
2. 打开界面与文档：
   - Web UI：http://localhost:3003
   - Swagger：http://localhost:3003/swagger
3. 远程执行一个 MCP 工具（示例）：
   ```bash
   curl -X POST http://localhost:3003/api/v1/packages/run \
     -H "Content-Type: application/json" \
     -d '{"packageName":"@modelcontextprotocol/server-everything","toolKey":"echo","inputData":{"message":"hello"},"envs":{}}'
   ```

## 简介

ToolSDK MCP Registry 可自托管私有 MCP 网关/注册表，提供 OpenAPI、远程工具执行、沙盒与 OAuth 2.1；也可作为 SDK 查询结构化的 MCP server 清单与配置。

- **适合谁：** 需要“可搜索的 MCP 资产库 + 可审计的远程执行网关”的团队
- **可搭配：** Docker；MCP server（stdio + Streamable HTTP）；任意 HTTP 客户端；OpenAPI/Swagger
- **准备时间：** 10–20 分钟

## 实战建议

- 量化信息：README 提到该注册表包含 **4,547+** 公共 MCP server 的结构化元数据。
- 量化信息：默认本地端口为 **3003**（UI + Swagger），方便快速自检。

## 落地方式：把“注册表”当基础设施

不要把它当成“更大的清单”，而是当成可控的基础设施：

1. **先划清信任边界。** 生产环境只保留少量 allow-list；私有部署时可按需裁剪 `packages/`。
2. **发现与执行分离。** 搜索可以开放，但远程执行（`run`）必须走受控环境与审批策略。
3. **统一密钥注入方式。** 对 `x-mcp-env-*` 这类注入方式做约束：短期凭证、按工具映射、可审计。

## 推荐上线清单

- 先选 5–10 个你们最常用的工具（GitHub、抓取文档、只读 DB）跑通闭环。
- 对执行量与错误率加监控；突增通常意味着策略退化。
- 若要对外暴露 Streamable HTTP 网关，先上鉴权与限流。

### FAQ

**它只是 MCP 清单吗？**
答：不是。它还提供自托管网关：搜索、远程执行与 OpenAPI 文档。

**STDIO 的 server 也能远程跑吗？**
答：README 描述了通过 Streamable HTTP 代理暴露已注册的包。

**怎么保证安全？**
答：用 allow-list、限制环境变量注入，并把远程执行收敛到受控环境。

## 来源与感谢

> Source: https://github.com/toolsdk-ai/toolsdk-mcp-registry
> License: MIT
> GitHub stars: 172 · forks: 84


---
Source: https://tokrepo.com/en/workflows/toolsdk-mcp-registry-private-gateway-sandbox
Author: MCP Hub