How to add MCP connections to a Notion Custom Agent

MCP connections let a Notion Custom Agent read from external apps and take actions there. Use a pre-configured server—Linear, Ramp, Figma, and the rest of Notion’s list—or connect a tool that hosts an MCP server at a publicly available URL.

Connections are available on Business and Enterprise plans only. Tools from a connected server work with every trigger type documented for Custom Agents: scheduled runs, runs triggered by Notion or Slack events, and manual runs from chat or @mentions.

Native integrations are a separate path. Slack, for example, is built into Notion, must be authorized by a workspace owner first, and can provide triggers plus read and write access. MCP servers follow an open protocol. Notion’s help page says any workspace member can add them, they support read and write, and they do not add triggers. Custom URLs still need the admin switch below. Both work with Custom Agents. MCP is the flexible option for tools Notion has not built in.

Each MCP connection is unique to a single Custom Agent and uses the credentials of the person who authenticated it. Connections are not shared, even when two agents use the same service.

Connect Figma on agent A, and agent B still needs its own Figma connection and its own login. Revoking a connection on one agent does not affect the others. You also cannot put two accounts for the same service on one agent. Separate accounts mean separate Custom Agents.

People with Full Access or Can Edit can add connections, chat with the agent, use every connected tool—even tools they cannot open outside the agent—view the activity log and MCP tool usage, remove a connection, and reconnect or update credentials. If they set the connection up, they can enable or disable tools and change how those tools run.

After the connection exists, only the person who authenticated it can configure and update tool settings, even if someone else has Full Access or Can Edit. The agent uses that person’s credentials and permissions on the external service.

Someone with Can view and interact can chat, use connected tools, trigger read and write actions, approve or cancel a write when confirmation is required, and see which servers are connected in settings. They cannot add or remove connections, change enabled tools, change execution settings, or view the full activity log.

Add a pre-configured connection

These apps connect without extra configuration: Amplitude, Attio, Box, ClickHouse, Figma, GitHub, HubSpot, Intercom, Linear, Mercury, Miro, Mixpanel, n8n, Ramp, Stripe, Sentry, and Wiz. Available tools vary by server.

Open your Custom Agent’s Settings.
Go to Tools & Access.
Click Add connection, then Add.
Choose a pre-configured server.
Follow the authentication prompts to connect your account.
Select the tools from that server you want the agent to use.
Click Connect.

Open the custom-server gate

A server that is not on that list needs a workspace admin first. Two settings are separate: one allows custom MCP servers, and one decides whether members can install any connection or only approved ones.

To allow custom MCP servers:

As a workspace admin, go to Settings, then Connections.
In the Manage tab, toggle on Enable custom MCP servers.

To limit what members can install:

As a workspace admin, go to Settings, then Connections.
In the Manage tab, find the Manage permissions section.
Next to Limit which connections members can install, choose one:
- Approved & recommended automatically approves all connections recommended by Notion.
- Approved only means you manually select each connection members can install.
Select Approved connections to review what members can install.
Select Add approved connection, then choose what to allow:
- Connections: search by name or ID and add it to the approved list.
- Custom MCP server: add one specific custom MCP server URL.
Click Save.

Anyone in the workspace can then use those approved options while setting up a Custom Agent. They still sign in with their own credentials. Approval does not share a login.

Add the custom server to the agent

Open the Custom Agent’s Settings.
Go to Tools & Access.
Click Add connection, then Custom MCP server.
Enter the MCP server’s URL from the tool or provider you are connecting to. Notion’s example is a URL from your company’s internal tool team.
Add a display name if you want one. This is optional.
Add any required authentication details.
Click Connect.

Custom servers may support OAuth, header-based authentication, or both. Header-based authentication covers API keys and bearer tokens.

Some OAuth servers do not support dynamic client registration. Notion has to pre-register a client application with that service before OAuth sign-in works. If the server does not support dynamic client registration, check its documentation for an API key or bearer token. If neither is available, that MCP server cannot be used with Custom Agents.

Leave writes on Always ask

In the agent’s Settings, under Tools & Access, expand the connection. Each tool has a toggle so you can enable or disable it.

Read tools—search, fetch, list, view—retrieve or view information and do not change external systems. Write tools—create, update, delete, send, post—change data outside Notion. By default they require confirmation before the agent runs them. The prompt shows the exact action.

Run automatically skips confirmation. That setting is documented as best for read tools, because they do not modify data.
Always ask makes someone approve or cancel first. This is the default for write tools, so the agent does not make unintended changes.
Always allow permanently approves every tool from that server and removes later confirmation prompts.

Always allow is not a single-tool override. It drops confirm-on-write for every tool on that server.

Disconnect only if the schedule can live without it

Open the agent’s Settings, go to Tools & Access, find the connection, click Disconnect, and click Disconnect again to confirm. Test the agent afterward. You can reconnect by authenticating again.

Once the connection is gone, the agent cannot reach that service. Scheduled runs that depend on the server may fail, and workflows can break as soon as you disconnect.

If tools never appear, refresh the agent settings page, look for a green checkmark or a Connected status, and confirm the server is online and returning tool metadata. Reconnect, or disconnect and add the server again.

If a run fails with an MCP error, open the Activity tab for the message. Tokens may have expired, so check that the connection is still valid and still enabled, then reconnect to refresh credentials. You can also name the server in the agent’s instructions. Notion’s example is: “Use Linear MCP to retrieve metadata for this mock.”

If the MCP server is down or unreachable, the agent reports an error in the run log. Tools from that server fail, but they do not crash the whole agent. Check the Activity tab for the message.

What to try next

On one Custom Agent, open Settings, then Tools & Access, and add a pre-configured app you already use. Leave write tools on Always ask and send a manual chat message so you can approve or cancel before anything is created or updated. For a server that is not on the list, have a workspace admin enable custom MCP servers and, if installs are limited, approve that exact URL before you paste it in. Re-read the ownership note before you disconnect anything a schedule already depends on.

Sources

MCP connections for Custom Agents