MCP OAuth connectors — Notion, Higgsfield, and any standard remote MCP

Some hosted MCP servers do not accept a static access token. They answer an unauthenticated initialize with HTTP 401 and a WWW-Authenticate: resource_metadata=… challenge. Synaplan then follows the standard path:

1. RFC 9728 protected-resource metadata
2. RFC 8414 authorization-server metadata
3. RFC 7591 dynamic client registration (no vendor app to pre-create)
4. Authorization-code + PKCE sign-in in the browser
5. Bearer access token on every outbound MCP call

This is a generic mode on Channels → MCP Servers. Notion and Higgsfield are the first hosted templates; any other spec-compliant remote MCP works the same way from a custom URL.

Ships off. An administrator must turn on MCP.OAUTH_CONNECTORS_ENABLED before users see the Notion / Higgsfield cards or the Connect button. Existing token-based servers are unchanged.

See also the MCP overview.

Administrator: turn the feature on

1. Open System Configuration → Channels → MCP servers.
2. Enable Let users connect remote MCP servers that sign in with OAuth.
3. Leave Allow the assistant to call connected MCP servers on (that is the existing master switch MCP.CLIENT_ENABLED).

Seeding is insert-if-missing. An operator 0 or 1 row is never overwritten on deploy.

The redirect URI that every remote authorization server will call is:

https://YOUR-SYNAPLAN-HOST/api/v1/mcp-servers/oauth/callback

On Synaplan Cloud that is https://web.synaplan.com/api/v1/mcp-servers/oauth/callback. Dynamic registration sends this URI automatically — you do not register a Notion or Higgsfield developer app.

User: connect Notion

1. Channels → MCP Servers → Start from → Notion.
2. Save the server (the URL is prefilled as https://mcp.notion.com/mcp).
3. Click Connect and allow Synaplan access in the Notion consent screen.
4. You return to Channels → MCP Servers with status Connected.
5. Test connection lists Notion tools (search, fetch, …).
6. Enable MCP Data Sources on at least one task (usually General Chat).
7. Ask in chat, for example: "Find the onboarding page in Notion and summarize it."

Notion does not accept an ntn_… integration token on this MCP endpoint. Sign-in is required.

User: connect Higgsfield

1. Channels → MCP Servers → Start from → Higgsfield.
2. Save (https://mcp.higgsfield.ai/mcp) → Connect → allow access.
3. Test connection lists tools.
4. History / asset reads go through the existing mcp_fetch path (read-only).
5. Image or video generation costs Higgsfield credits. Turn on Allow write actions on that server first; otherwise the assistant only reads.

Higgsfield may issue an access token without a refresh token. When it expires, the chip shows Action needed (reconnect) — click Reconnect. That is expected, not a broken connection.

Custom OAuth MCP server

Any remote Streamable HTTP MCP that speaks the same discovery flow works without a template:

1. Start from → Custom server.
2. Paste the HTTPS MCP URL (for example https://mcp.example.com/mcp).
3. Set auth mode to OAuth when you save (or pick a template that does).
4. Connect — Synaplan discovers the authorization server, registers itself, and opens the consent screen.

The server must:

• Advertise resource_metadata on 401 (or serve /.well-known/oauth-protected-resource / …/mcp).
• Support PKCE S256.
• Expose a registration endpoint (token_endpoint_auth_method: none).

If Test connection returns HTTP 401 and mentions sign-in, use Connect instead of pasting a token.

Example configurations

These are the rows Synaplan stores after you save (secrets are encrypted and never returned by the API). Use them as a reference for support or for a custom remote MCP that looks the same.

Notion (hosted)

{
  "name": "Notion",
  "url": "https://mcp.notion.com/mcp",
  "auth_mode": "oauth",
  "enabled": true,
  "allow_write": false
}

Discovered endpoints (filled in automatically on Connect):

Higgsfield (hosted)

{
  "name": "Higgsfield",
  "url": "https://mcp.higgsfield.ai/mcp",
  "auth_mode": "oauth",
  "enabled": true,
  "allow_write": false
}

Set "allow_write": true only when users should generate media (credits).

Token-based server (unchanged)

{
  "name": "Company CRM",
  "url": "https://crm.example.com/mcp",
  "auth_mode": "bearer",
  "auth_header": "Authorization",
  "auth_token": "Bearer sk-…",
  "enabled": true,
  "allow_write": false
}

REST API — start sign-in

# After the server row exists:
curl -X POST "https://web.synaplan.com/api/v1/mcp-servers/42/oauth/start" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json"

# → { "success": true, "authorize_url": "https://mcp.notion.com/authorize?…" }
# Send the browser to authorize_url. The provider redirects to:
#   /api/v1/mcp-servers/oauth/callback?code=…&state=…
# which then redirects to /channels/mcp?connected=42

Status chips

What the assistant can do once connected

• Notion search/fetch tools are read-safe → they appear in mcp_fetch as soon as a topic has MCP Data Sources on.
• Higgsfield reads → mcp_fetch. Generation tools stay behind Allow write actions.
• Same tenant isolation, SSRF guard, and timeouts as token-based MCP servers.

Out of scope

stdio / npx servers (the cluster cannot spawn them), SSE-only transport, device-code flow, and pre-registered vendor OAuth apps. Those stay out of Synaplan Cloud.

See also

• MCP — Server & Client
• Code examples
• Multi-Task (DAG) Routing
• Model Context Protocol specification