The key is wrong, or it was rolled, revoked or deleted. Copy the current key with View Key on the Integrations page, and check that the header reads Bearer so_….
AI agents & MCP server
Connect an AI assistant such as Claude, Cursor or Perplexity to Sotion through MCP, the standard way assistants use outside tools. We run two MCP servers:
The Sotion connector (
https://api.sotion.so/mcp): sets up a new site from a Notion page. Anyone can use it, without a key.The site MCP server (
https://api.sotion.so/api/v1/mcp/http): manages one site's members and access groups with an API key. It's part of the Pro and Scale plans and of the 14-day free trial.
Set up a site from your assistant
Your assistant checks your Notion page, creates the site and has us email you an activation link. Your site goes live at its Sotion address when you click Activate site in that email.
Add the Sotion connector to your assistant, with the address
https://api.sotion.so/mcp. The steps for each assistant are on sotion.so/ai.Ask your assistant to publish your Notion page with Sotion, and give it the page's link and your email address.
Open the activation email we send you and click Activate site within 48 hours.
The Notion page must be published to the web: in Notion, use Share → Publish. If it isn't, your assistant tells you how.
Clicking the link creates your Sotion account, or adds the site to the account you already have with that email address. If your plan has no room for another site, nothing is created.
The connector only sets up new sites. To manage a site you already have, use the site MCP server.
Manage your members with the site MCP server
With an API key, your assistant can look up, add, change and remove your site's members and access groups, and send sign-in links, from plain requests such as "Add [email protected] to the Premium group".
You need the Pro or Scale plan, or the free trial, and an API key from the Integrations page of your site dashboard, as API & Webhook Integrations shows. Only Owners can create keys, and the key decides which site your assistant works on.
Add it to your assistant
Your assistant sends the key in an Authorization header, as Bearer so_…. Replace so_your_api_key below with your key, and keep it private: anyone who has it can change your members.
Claude Code: run this in your terminal.
claude mcp add --transport http sotion https://api.sotion.so/api/v1/mcp/http \
--header "Authorization: Bearer so_your_api_key"Cursor: add the server to your mcp.json.
{
"mcpServers": {
"sotion": {
"url": "https://api.sotion.so/api/v1/mcp/http",
"headers": {
"Authorization": "Bearer so_your_api_key"
}
}
}
}Claude Desktop and other assistants that can't send a header: connect through the mcp-remote bridge, which needs Node.js on your computer. In Claude Desktop, add this to claude_desktop_config.json (Settings → Developer → Edit Config), then restart Claude Desktop.
{
"mcpServers": {
"sotion": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://api.sotion.so/api/v1/mcp/http",
"--header",
"Authorization:${AUTH_HEADER}"
],
"env": {
"AUTH_HEADER": "Bearer so_your_api_key"
}
}
}
}Connectors you add by address alone, such as Claude.ai's custom connectors, can't send the key, so they can't use this server.
What your assistant can do
Tool | What it does |
|---|---|
| Checks that our API is up |
| Shows the site the key belongs to: its address, title and whether it's published |
| Lists members, filtered by email, status, verified or paid, up to 100 at a time |
| Finds members by part of their email or name |
| Shows one member with their access groups |
| Adds a member, optionally to access groups |
| Adds up to 500 members at once |
| Changes a member's details, or blocks or unblocks them |
| Deletes a member; this can't be undone |
| Emails a member a sign-in link |
| Lists access groups with their member counts |
| Shows one access group |
| Creates an access group |
| Renames an access group or changes its description |
| Deletes an access group but not its members; this can't be undone |
| Lists the members of an access group |
| Adds a member to an access group |
| Removes a member from an access group, not from your site |
Your assistant works through our API with your key: the same plan check, the same limits (300 reads and 60 changes a minute for each key) and the same webhooks as your own API requests.
Access groups that Scoped Access makes from your Notion database are read-only here: your assistant can list them and their members but can't change them.
Adding a member sends them no email. Ask your assistant to send a login link when they should get one.
send_login_link sends a real email, and delete_member and delete_access_group can't be undone. Check what your assistant is about to do before you let it run one of them.
Example requests
"List the members who are blocked."
"Add [email protected] as a member and put them in the Premium group."
"How many members are in each access group?"
"Send a login link to [email protected]."
Troubleshooting
Every request fails with "Invalid or missing API key."
Requests fail with "API access requires the Pro plan or higher."
Your plan doesn't include the API, for example after the free trial ends. Requests work again once you move to Pro or Scale.
My assistant can't connect, or asks me to sign in
It isn't sending the Authorization header. Add the header as shown above, or connect through mcp-remote.
The connector says my Notion page isn't published
In Notion, open the page, use Share → Publish and publish it, then ask your assistant to check again.
Related articles
API keys and webhooks: API & Webhook Integrations.
Every request the API takes: the REST API reference.
What each plan includes: Understanding your plan.
Was this helpful?
Was this helpful?