Connect a chat assistant (OAuth)
Chat assistants that can use remote MCP servers with a sign-in — usually called custom connectors, sometimes behind a developer mode — connect to NorReach with OAuth. There is no API key to paste: you sign in to NorReach, choose what the assistant may do, and it acts as you. It can never do more than your role allows, and it sees only your workspace.
Before you start
- The API is switched on for your workspace (early access — an owner or admin requests it in Settings › API & webhooks).
- You are an owner or an admin. Members can connect too once an owner switches on "Members may connect AI apps" in Settings › API & webhooks › Connected apps.
- Your assistant supports remote MCP servers over Streamable HTTP with OAuth. If yours only takes a URL and headers, use an API key instead (Connect an assistant).
Add NorReach as a custom connector
- In your assistant's settings, open connectors (or apps, tools or integrations) and choose to add a custom connector. Some assistants ask you to switch on a developer mode first; on team plans, an admin of the assistant may have to allow custom connectors.
- Name it NorReach and paste the server URL
https://api.norreach.app/mcp. Leave any client ID and client secret fields empty — the assistant registers itself. - Choose connect. The assistant opens NorReach in your browser; sign in if you aren't already.
- Check the consent screen: the assistant's name (always marked unverified — NorReach can't vouch for an app it didn't build), the address it returns to after you answer, your workspace and the email you are signed in with.
- Tick the scopes you want to give, then Allow. You are back in the assistant, and NorReach's tools appear there.
Which scopes to give
The consent screen lists only the scopes your role can give. Start small — you can connect again later to change your answer.
| You want the assistant to | Give |
|---|---|
| Look things up: contacts, campaigns, the inbox, calls, meetings, pages, results | The read scopes (18) — ticked by default |
| Also prepare work: add contacts, draft campaigns and pages, ask Nora for a plan | Also contacts:write, campaigns:write, plans:write, pages:write |
| Send, call, launch, publish, spend, decide approvals, change access | Only the red scopes you need, one by one — see below |
Red scopes (18 of them: reaching people, spending, publishing, erasing, deciding approvals, changing people's access) start unticked. To tick one you must have signed in during the last 10 minutes — the screen offers "Sign in again". Without a red scope the assistant still looks things up, drafts and previews, and you do the rest in the app.
What keeps it safe
- Tools that reach people, spend, publish, erase or decide take confirm: the first call is a preview that changes nothing, the assistant shows it to you, and only your yes runs it. Most assistants also ask before they run such a tool.
- Messages and calls the assistant asks for wait in Approvals unless your workspace sends without approval and you gave approvals:decide — and every send check (consent, do-not-contact, quiet hours) still runs.
- Text from outside — an email, a form, a web page — is data to the assistant, never instructions. If it suggests acting on something it read, check first.
- No tool makes or searches ads; Nora makes ads in a plan. Everything the assistant does is in the audit log as you, through the assistant's name.
Change or disconnect
- To change the scopes, connect again from the assistant (reconnect). Your new answer replaces the old one and the assistant's earlier access stops.
- To disconnect, open Settings › API & webhooks › Connected apps (owners and admins see everyone's) or Settings › Security (your own) and choose Disconnect. It takes effect on the assistant's next request; it will ask you to connect again.
- Removing the connector inside the assistant doesn't always tell NorReach — disconnect it here too.
- If you leave the workspace or are switched off, your connections stop. Your role is read on every request: if it changes, so does what the assistant can do.
Troubleshooting
| What you see | Why |
|---|---|
| NorReach says you can't connect apps | You are not an owner or admin and the members switch is off, or the API isn't on for your workspace. |
| The assistant keeps asking you to connect | The connection was disconnected in Settings, went unused for 60 days, or a sign-in token was used twice — NorReach then stops the whole connection to be safe. Connect again. |
| A tool you expected is missing | You didn't give its scope (connect again and tick it), or your role can't do it. |
| An error page instead of the consent screen | The assistant's return address isn't one NorReach accepts (https, or http on this computer only). Use an API key with that assistant instead. |
How it works (for developers)
Without a token, https://api.norreach.app/mcp answers 401 with:
WWW-Authenticate: Bearer realm="NorReach MCP", resource_metadata="https://api.norreach.app/.well-known/oauth-protected-resource/mcp"The assistant reads the protected-resource metadata there, then the authorization server metadata, registers (dynamic client registration, or a client ID metadata document), sends you to the consent screen with PKCE (S256) and resource=https://api.norreach.app/mcp, and exchanges the code for tokens. An expired or revoked token answers 401 with error="invalid_token"; the assistant refreshes, or asks you to connect again. Details: OAuth.