MCP

MCP (Model Context Protocol) is a standard way for AI clients (Claude, Cursor, VS Code Copilot and others) to call an app's features as tools. Point one of those clients at Synq and it can list your projects, kick off deployments, check logs, add domains, look at a server's disk usage, check that panel backups run, and more, using the exact same permissions you'd have yourself.

The important part: it's not a second, looser door into Synq. Every tool call re-runs the full auth and permission stack, so an agent can only ever see and do what its credential is allowed to, nothing more.

The endpoint

The endpoint lives on your panel's host, the address in SYNQ_PUBLIC_URL:

https://app.<domain>/api/mcp

app.<domain> stands for the host you open the panel on, for example panel.example.com. A few things worth knowing up front:

• It's a stateless Streamable-HTTP JSON-RPC 2.0 endpoint: request in, response out.
• It's POST-only. An authenticated GET returns 405 (there's no server-to-client stream to open); an unauthenticated GET returns 401 with the pointer OAuth clients use to find the sign-in.
• No batching: send one JSON-RPC message per request, not an array.
• The OAuth discovery documents are on the same host: /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource/api/mcp.

You rarely type this URL by hand. Settings, MCP shows it pre-filled under Endpoint, with a copy button.

Connect a client

There are two ways to authenticate, and most clients pick one for you. Use the tab that matches your client.

claude mcp add --transport http synq https://app.<domain>/api/mcp

codex mcp add synq --url https://app.<domain>/api/mcp
codex mcp login synq

{
  "mcpServers": {
    "synq": {
      "url": "https://app.<domain>/api/mcp",
      "headers": { "Authorization": "Bearer synq_pat_…" }
    }
  }
}

claude mcp add --transport http synq https://app.<domain>/api/mcp \
  --header "Authorization: Bearer synq_pat_…"

Every call is re-checked

This is the heart of the security model, and it's why MCP access is as safe as your token:

• Authenticating once resolves your capability, but that's used only to filter tools/list, so a client isn't shown tools its token could never use.
• The real gate runs on every tools/call: the endpoint builds an internal request, forwards your bearer, and dispatches it through the same routes, validation, auth middleware and per-resource permission check as a normal HTTP call.

The practical upshot: a read-only token can only reach read tools, and a scoped token stays boxed into its granted resources. A scoped token isn't even shown the org-wide list and create tools: get_projects (list every project) simply won't appear in its tools/list; it sees only the per-resource tools for the resource types it was granted. And if a tools/call touches something outside that scope, it comes back 404: the scope doing its job. For the full protocol details (JSON-RPC methods, negotiation, error codes), see the MCP API reference.

The organization boundary applies to MCP exactly as it does to a browser session: because every call runs through the same per-resource permission check, an MCP client acts only within organizations you belong to and can never reach another org's projects, servers or secrets. A resource outside your membership comes back 404, just as it would in the dashboard. See Isolation.

Instance-wide operations (panel backups, a Docker cleanup, the certificate contact email, system jobs) additionally need an instance administrator's credential, as they do in the dashboard.

Which tools map to which API

Tools aren't a separate feature set: each one maps onto a permission-tagged REST route, and the tool name is built from that route's method and path, without the /api prefix. So get_projects is GET /api/projects, post_domains is POST /api/domains, and patch_projects_by_id is PATCH /api/projects/:id. Call tools/list to see the exact set your token can use.

Not every route is a tool: a route becomes one only when it opts in, so the set is a curated slice of the API rather than the whole surface. Each exposed tool also carries two hints a client can surface: readOnlyHint (the tool only reads) and destructiveHint (it deletes or tears something down), so an agent UI can flag a destructive call before it runs.

Guided flows

Some tasks are a chain of calls in a specific order: deploying a repo, uploading a folder, installing a catalog app. The server ships a small set of prompts (prompts/list / prompts/get) that spell those chains out step by step, referencing the exact tools to call. Compatible clients surface them as slash-commands or starters, so an agent can pick a flow and follow it rather than reverse-engineering the order from the flat tool list. See the MCP API reference for the full catalog.

Verify from the terminal

To confirm a token works and see what it can do, ask for the tool list:

curl -s https://app.<domain>/api/mcp \
  -H "Authorization: Bearer synq_pat_…" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

This returns exactly the tools that token is allowed to call.

Manage connected clients

Every OAuth client you've approved is listed under Settings, MCP, Connected clients, tagged Read-only or Full control, with All resources or how many resources it can reach, when it was authorized, when it was last used and how many calls it made.

• Edit access changes what the client can reach. Changes apply on the agent's next request; it doesn't need to reconnect. Removing every restriction asks for a second confirmation.
• Activity opens the audit log filtered to that client, so you see exactly what it did. Everything an agent changes is recorded with the source AI assistant.
• Disconnect revokes the client's issued tokens immediately and drops its consent, so it has to re-authorize next time.

The same list and controls are available programmatically via the Tokens API.

After the panel moves

OAuth tokens are issued for one endpoint address. If you move the panel to another host (see Domains for the panel and your apps), the old tokens are refused at the new address: remove Synq from each OAuth client, add https://<new host>/api/mcp, and approve it again. Clients that use a static token only need the new URL.

Troubleshooting

Related guides