cloudflare / cloudflare/cloudflare-os
Document the exact portal_list_servers response format the MCP Server Portals connector parses
- Dominant language
- TypeScript
- Stars
- 9.9k
- Forks
- 1.2k
- Avg merge
- 1d 20h
- Merged PRs (30d)
- 107
Description
**Context**
`packages/gatekeeper-mcp-portal/README.md` describes the portal contract as two facts: tools are named `{server_id}_{original_name}` (split on the first underscore), and `portal_list_servers` "returns each upstream server's id, name, and enabled state". The second fact is not specific enough to implement against.
The actual parser (`packages/mcp-shared/src/portal.ts`, `parseServerLine` / `parsePortalServers`) accepts either:
- `structuredContent: { servers: [{ id, name, enabled }] }`, or
- text content with bullet lines of the form `- {display name} ({server id}): {status}`, where the status is treated as disabled when it contains "disabled", "✗" or "✘", e.g.
```
Available MCP Servers:
- Mini DWH (dwh): ✓ enabled
- Mini ERP (erp): ✓ enabled
```
Unrecognized lines are skipped and the listing is marked incomplete.
**Why it matters**
We put a self-hosted gateway (agentgateway) in front of our MCP servers. It already emits the `{target}_{tool}` prefix, so the only missing piece was a `portal_list_servers` tool. Getting its output accepted required reading the parser source. With the format documented, third-party gateways and small adapters can implement the portal contract without guessing.
**Suggestion**
Add the two accepted shapes (structured and text) and the disabled-status rule to the "How upstream servers are recovered" section of the connector README, next to the naming rule. Mentioning that `portal_*` tools are never grantable would round it out.
**Environment**
cloudflare-os main @ c0b6f3e (2026-09-04); the README on current main still describes the response only as "id, name, and enabled state".
Contributor guide
Research direction
Start with packages/gatekeeper-mcp-portal/README.md and its “How upstream servers are recovered” section, then read parseServerLine and parsePortalServers in packages/mcp-shared/src/portal.ts. Confirm the README covers both structuredContent and text responses, the disabled-status rule, skipped lines, incomplete listings, and the portal_* grantability note. Done means a third-party gateway can implement portal_list_servers without reading parser source.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 90/100