# MCP servers (/web/api/mcp-servers)





`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 [#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 [#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 [#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 [#response-shape]

```typescript
type MogplexApiMcpServer = {
  name: string;                          // unique per user
  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 [#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 [#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 [#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 [#read-next]

* [Connections and MCP](/configure-and-extend/connections-and-mcp) — the
  product configuration model behind MCP server sync
* [MCP server (JSON-RPC)](/web/api/mcp) — the v1-as-MCP-tools surface
* [Authentication](/web/api/authentication) — PAT lifecycle and scopes