docs(api): document v1 MCP servers listing endpoint #37
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,129 @@ | ||
| --- | ||
| title: MCP servers | ||
| description: GET /api/v1/mogplex/mcp/servers returns the caller's configured MCP servers — both custom user_mcp_servers and enabled mcp_server connections — with secrets already resolved server-side, ready to hand to a local MCP client. | ||
| --- | ||
|
|
||
| import { Callout } from 'fumadocs-ui/components/callout'; | ||
|
|
||
| `GET /api/v1/mogplex/mcp/servers` | ||
|
|
||
| Returns the merged list of MCP servers the authenticated user has configured | ||
| in Mogplex Cloud: custom servers stored in `user_mcp_servers` plus enabled | ||
| `mcp_server` connections. Secret values (env vars, headers, OAuth tokens) are | ||
| resolved server-side from Supabase Vault before the response is sent, so the | ||
| returned `config` block is ready to hand straight to a local MCP client. | ||
|
|
||
| <Callout type="info"> | ||
| Don't confuse this with [`POST /api/v1/mogplex/mcp`](/web/api/mcp). That | ||
| endpoint is the JSON-RPC tool-call surface for the **v1 REST API itself**. | ||
| This one lists the **user's external MCP servers** so a CLI or agent host | ||
| can connect to them locally. | ||
| </Callout> | ||
|
|
||
| ## Scope | ||
|
|
||
| `read` — see [Authentication → Scopes](/web/api/authentication#scopes). The | ||
| listing is gated on `read` explicitly because the response surfaces | ||
| authorization headers and vault-decrypted env vars. | ||
|
|
||
| ## Merge rules | ||
|
|
||
| When a `user_mcp_servers` entry and an enabled `mcp_server` connection share | ||
| a name, the custom row wins — same precedence the CLI uses today via the | ||
| internal `/api/mcp-servers?format=cli` endpoint. | ||
|
|
||
| ## Example | ||
|
|
||
| ```bash | ||
| export MOGPLEX_BASE_URL="https://www.mogplex.com" | ||
| export MOGPLEX_TOKEN="mog_..." | ||
|
|
||
| curl -sS \ | ||
| -H "Authorization: Bearer $MOGPLEX_TOKEN" \ | ||
| "$MOGPLEX_BASE_URL/api/v1/mogplex/mcp/servers" | ||
| ``` | ||
|
|
||
| Representative response: | ||
|
|
||
| ```json | ||
| { | ||
| "ok": true, | ||
| "data": { | ||
| "servers": [ | ||
| { | ||
| "name": "supabase", | ||
| "enabled": true, | ||
| "config": { | ||
| "command": "npx", | ||
| "args": ["@supabase/mcp-server"], | ||
| "env": { | ||
| "SUPABASE_ACCESS_TOKEN": "sbp_••••••••" | ||
| } | ||
| } | ||
| }, | ||
| { | ||
| "name": "linear", | ||
| "enabled": true, | ||
| "config": { | ||
| "url": "https://mcp.linear.app/sse", | ||
| "http_headers": { | ||
| "Authorization": "Bearer lin_••••••••" | ||
| } | ||
| } | ||
| } | ||
| ] | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ## Response shape | ||
|
|
||
| ```typescript | ||
| type MogplexApiMcpServer = { | ||
| name: string; // unique per user | ||
|
There was a problem hiding this comment. Warning: Response example contradicts the documented disabled-server behavior The type comment on Suggestion: Add a third server entry with |
||
| enabled: boolean; // disabled servers are still returned | ||
| config: Record<string, unknown>; // stdio: command/args/env | ||
| // http: url/http_headers | ||
| }; | ||
| ``` | ||
|
|
||
| `config` is intentionally a loose record so the server can add transport | ||
| options without bumping the CLI. The two shapes in use today: | ||
|
|
||
| ```typescript | ||
| // stdio | ||
| { command: string; args?: string[]; env?: Record<string, string> } | ||
|
|
||
| // http | ||
| { url: string; http_headers?: Record<string, string> } | ||
| ``` | ||
|
|
||
| ## Errors | ||
|
|
||
| | Code | HTTP | Cause | | ||
| | ----------------- | ---- | ---------------------------------- | | ||
| | `UNAUTHORIZED` | 401 | Missing/invalid/expired PAT | | ||
| | `FORBIDDEN` | 403 | PAT lacks the `read` scope | | ||
| | `RATE_LIMITED` | 429 | 60 req/min per PAT exceeded | | ||
| | `INTERNAL_ERROR` | 500 | Unexpected server error | | ||
|
|
||
| See [Errors](/web/api/errors) for retry guidance. | ||
|
|
||
| ## CLI equivalent | ||
|
|
||
| The Mogplex CLI calls this endpoint automatically on startup to refresh | ||
| `~/.mogplex/mcp-servers.remote.json`. There's no dedicated subcommand — see | ||
| [Headless runs](/cli/automation/headless-runs) for how the CLI uses these | ||
| servers during agent runs. | ||
|
|
||
| ## Security notes | ||
|
|
||
| - Responses include decrypted secrets. Treat them like a `.env` file: don't | ||
| log them, don't commit them, don't echo them in CI output. | ||
| - The endpoint requires the `read` scope and never falls back to session | ||
| cookies — a PAT is the only way in. | ||
|
|
||
| ## Read next | ||
|
|
||
| - [MCP server (JSON-RPC)](/web/api/mcp) — the v1-as-MCP-tools surface | ||
| - [Authentication](/web/api/authentication) — PAT lifecycle and scopes | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -8,6 +8,7 @@ | |
| "runs", | ||
| "repos", | ||
| "sandboxes", | ||
| "mcp-servers", | ||
| "mcp", | ||
| "working-requests", | ||
| "route-families" | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Suggestion: "export" verb in index.mdx inherited from the old CLI-specific path
The updated line reads:
GET /api/v1/mogplex/mcp/serversto export the CLI-ready MCP view (PAT-only). The verb "export" and the phrase "CLI-ready" were carried over from the old/api/mcp-servers?format=clientry, which was explicitly a CLI export format. The v1 endpoint is a general listing — the CLI just happens to consume it. Consider:GET /api/v1/mogplex/mcp/serversto list configured MCP servers with secrets resolved (PAT-only). This matches the description on the new reference page and sets accurate expectations for non-CLI callers.