{"id":30674390,"url":"https://github.com/stacklok/toolhive-registry","last_synced_at":"2026-02-19T02:04:33.588Z","repository":{"id":311134305,"uuid":"1035921321","full_name":"stacklok/toolhive-registry","owner":"stacklok","description":"ToolHive's registry of MCP servers","archived":false,"fork":false,"pushed_at":"2025-12-22T17:59:05.000Z","size":152687,"stargazers_count":12,"open_issues_count":8,"forks_count":6,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-12-22T22:02:58.755Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stacklok.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.MD","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-11T09:44:01.000Z","updated_at":"2025-12-22T17:59:08.000Z","dependencies_parsed_at":"2025-09-21T02:23:13.124Z","dependency_job_id":"4d843585-5aae-451d-abe1-3d4fdb92f809","html_url":"https://github.com/stacklok/toolhive-registry","commit_stats":null,"previous_names":["stacklok/toolhive-registry"],"tags_count":130,"template":false,"template_full_name":null,"purl":"pkg:github/stacklok/toolhive-registry","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stacklok%2Ftoolhive-registry","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stacklok%2Ftoolhive-registry/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stacklok%2Ftoolhive-registry/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stacklok%2Ftoolhive-registry/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stacklok","download_url":"https://codeload.github.com/stacklok/toolhive-registry/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stacklok%2Ftoolhive-registry/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28017198,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-12-25T02:00:05.988Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-09-01T07:08:27.362Z","updated_at":"2026-02-19T02:04:33.582Z","avatar_url":"https://github.com/stacklok.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ToolHive Registry\n\nThis repository contains the registry of MCP (Model Context Protocol) servers available for ToolHive. Each server entry provides AI assistants with specialized tools and capabilities.\n\n## What is this?\n\nThink of this as a catalog of tools that AI assistants can use. Each entry in this registry represents a server that provides specific capabilities—like interacting with GitHub, querying databases, or fetching web content.\n\n## How to Add Your MCP Server\n\nAdding your MCP server to the registry is simple! You need to create a `server.json` file following the [upstream MCP ServerJSON schema](https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json), with ToolHive-specific extensions in the `_meta` field. We support two types of MCP servers:\n\n1. **Container-based servers** - Run as Docker containers (use `packages` field)\n2. **Remote servers** - Accessed via HTTP/HTTPS endpoints (use `remotes` field)\n\n### Step 1: Create a Folder\n\nCreate a new folder in `registries/toolhive/servers/` with your server's name (use lowercase and hyphens):\n\n```\nregistries/\n  └── toolhive/\n      └── servers/\n          └── my-awesome-server/\n              └── server.json\n```\n\n### Step 2: Create Your server.json File\n\nChoose the appropriate format based on your server type:\n\n#### For Container-based Servers\n\nCreate a `server.json` file:\n\n```json\n{\n  \"$schema\": \"https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json\",\n  \"name\": \"io.github.stacklok/my-server\",\n  \"description\": \"What your server does in one sentence\",\n  \"title\": \"my-server\",\n  \"repository\": {\n    \"url\": \"https://github.com/myorg/my-server\",\n    \"source\": \"github\"\n  },\n  \"version\": \"1.0.0\",\n  \"packages\": [\n    {\n      \"registryType\": \"oci\",\n      \"identifier\": \"ghcr.io/myorg/my-server:v1.0.0\",\n      \"transport\": {\n        \"type\": \"stdio\"\n      },\n      \"environmentVariables\": [\n        {\n          \"name\": \"API_KEY\",\n          \"description\": \"Your API key\",\n          \"isRequired\": true,\n          \"isSecret\": true\n        }\n      ]\n    }\n  ],\n  \"_meta\": {\n    \"io.modelcontextprotocol.registry/publisher-provided\": {\n      \"io.github.stacklok\": {\n        \"ghcr.io/myorg/my-server:v1.0.0\": {\n          \"tier\": \"Community\",\n          \"status\": \"Active\",\n          \"tags\": [\"api\", \"integration\"],\n          \"tools\": [\"tool_name_1\", \"tool_name_2\"]\n        }\n      }\n    }\n  }\n}\n```\n\n#### For Remote Servers\n\n```json\n{\n  \"$schema\": \"https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json\",\n  \"name\": \"io.github.stacklok/my-remote-server\",\n  \"description\": \"What your server does in one sentence\",\n  \"title\": \"my-remote-server\",\n  \"repository\": {\n    \"url\": \"https://github.com/myorg/my-server\",\n    \"source\": \"github\"\n  },\n  \"version\": \"1.0.0\",\n  \"remotes\": [\n    {\n      \"type\": \"streamable-http\",\n      \"url\": \"https://api.example.com/mcp\"\n    }\n  ],\n  \"_meta\": {\n    \"io.modelcontextprotocol.registry/publisher-provided\": {\n      \"io.github.stacklok\": {\n        \"https://api.example.com/mcp\": {\n          \"tier\": \"Community\",\n          \"status\": \"Active\",\n          \"tags\": [\"remote\", \"api\"],\n          \"tools\": [\"tool_name_1\", \"tool_name_2\"]\n        }\n      }\n    }\n  }\n}\n```\n\n### Key Concepts\n\n**The `_meta` extensions block** holds ToolHive-specific data (tier, status, tags, tools, permissions, etc.) nested under `io.modelcontextprotocol.registry/publisher-provided` \u003e `io.github.stacklok` \u003e `\u003cextension-key\u003e`.\n\nThe **extension key** must match:\n- For containers: the `packages[0].identifier` value (e.g., `ghcr.io/myorg/my-server:v1.0.0`)\n- For remotes: the `remotes[0].url` value (e.g., `https://api.example.com/mcp`)\n\n### Step 3: Add More Details (Optional but Recommended)\n\nYou can add more information in the `_meta` extensions block:\n\n```json\n{\n  \"ghcr.io/myorg/my-server:v1.0.0\": {\n    \"tier\": \"Community\",\n    \"status\": \"Active\",\n    \"tags\": [\"api\", \"integration\", \"productivity\"],\n    \"tools\": [\"tool_name_1\", \"tool_name_2\"],\n    \"permissions\": {\n      \"network\": {\n        \"outbound\": {\n          \"allow_host\": [\"api.example.com\"],\n          \"allow_port\": [443]\n        }\n      }\n    },\n    \"provenance\": {\n      \"cert_issuer\": \"https://token.actions.githubusercontent.com\",\n      \"repository_uri\": \"https://github.com/myorg/my-server\",\n      \"runner_environment\": \"github-hosted\",\n      \"signer_identity\": \"/.github/workflows/build.yml\",\n      \"sigstore_url\": \"tuf-repo-cdn.sigstore.dev\"\n    },\n    \"custom_metadata\": {\n      \"author\": \"My Organization\",\n      \"homepage\": \"https://docs.example.com\",\n      \"license\": \"MIT\"\n    }\n  }\n}\n```\n\n## Common Questions\n\n### What is \"transport\"?\n\nThis tells ToolHive how to communicate with your server:\n\nFor **container-based servers** (in `packages[].transport.type`):\n\n- `stdio` - Standard input/output (most common)\n- `sse` - Server-sent events\n- `streamable-http` - HTTP streaming\n\nFor **remote servers** (in `remotes[].type`):\n\n- `streamable-http` - HTTP streaming (recommended)\n- `sse` - Server-sent events (deprecated but still supported)\n- **Note:** Remote servers cannot use `stdio`\n\nIf you're not sure, use `stdio` for containers and `streamable-http` for remote servers.\n\n### What is \"tier\"?\n\n- `Official` - Maintained by the MCP team or platform owners\n- `Community` - Created and maintained by the community (most servers)\n\n### What is \"status\"?\n\n- `Active` - Fully functional and maintained\n- `Deprecated` - No longer maintained, will be removed\n\n### What about the \"tools\" field?\n\nList all the tools your server provides in the `_meta` extensions block. If your server's tools aren't knowable until runtime, you can use `[\"set_during_runtime\"]`.\n\n### Do I need a Docker image?\n\n**For container-based servers:** Yes. Your MCP server must be packaged as a Docker image and published to a registry like:\n\n- Docker Hub (`docker.io/username/image`)\n- GitHub Container Registry (`ghcr.io/username/image`)\n- Other public registries\n\n**For remote servers:** No. You just need to provide the URL endpoint where your MCP server is accessible.\n\n### Security Note: Filesystem Permissions\n\n**Important:** Don't specify filesystem paths or volume mounts in your registry entries. Mounting host directories is a security risk and should be configured by users at runtime, not in registry specs. Only network permissions (allowed hosts and ports) should be specified in the `permissions` section.\n\n### How do I test my entry?\n\nAfter adding your entry, you can validate it:\n\n```bash\n# Validate all entries\ntask catalog:validate\n\n# Build the registry files\ntask catalog:build\n```\n\nOr submit a pull request and our automated checks will validate it for you.\n\n## Submitting Your Entry\n\n1. Fork this repository\n2. Add your server entry as described above\n3. Submit a pull request\n4. We'll review and merge your addition\n\n### Registry Inclusion Criteria\n\nWe evaluate submissions based on several criteria to ensure quality and usefulness for the community. Your server should:\n\n- Provide clear value and unique capabilities\n- Be well-documented with accurate tool descriptions\n- Follow security best practices\n- Be actively maintained with recent updates\n\nFor detailed evaluation criteria, see the [Registry Criteria documentation](https://docs.stacklok.com/toolhive/concepts/registry-criteria).\n\n### Before Submitting, Please Ensure\n\nFor **container-based servers**:\n\n- [ ] Your Docker image is publicly accessible\n- [ ] The `description` clearly explains what your server does\n- [ ] You've listed all the tools your server provides\n- [ ] Any required environment variables are documented\n- [ ] Your server works with ToolHive\n\nFor **remote servers**:\n\n- [ ] Your server endpoint is publicly accessible\n- [ ] The `description` clearly explains what your server does\n- [ ] You've listed all the tools your server provides\n- [ ] Any required authentication is documented\n- [ ] The transport is set to `streamable-http` (preferred) or `sse` (not `stdio`)\n- [ ] Your server works with ToolHive's proxy command\n\n## Need Help?\n\n- Check existing entries in `registries/toolhive/servers/` for examples\n- Open an issue if you have questions\n- Join our community discussions\n\n## For Maintainers\n\nIf you need to work with the registry programmatically:\n\n```bash\n# Validate all entries\ntask catalog:validate\n\n# Build the registry files (both ToolHive and official MCP formats)\ntask catalog:build\n\n# Update metadata for oldest entries\ntask catalog:update-metadata:oldest\n\n# See all available commands\ntask\n```\n\n## License\n\nApache License 2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstacklok%2Ftoolhive-registry","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstacklok%2Ftoolhive-registry","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstacklok%2Ftoolhive-registry/lists"}