MCP connections
Connect an MCP client to Sift with your personal account or an organization API key. Use personal OAuth when the agent needs your permissions, app views, or human-confirmed replies.
At a glance
| Setting | Value |
|---|---|
| Server URL | https://mcp.getsift.ai/mcp |
| Transport | Streamable HTTP |
| Personal authentication | OAuth authorization code with PKCE |
| Service authentication | Authorization: Bearer <SIFT_API_KEY> |
| Access token lifetime | 90 days |
| Refresh token | Not supported; authenticate again |
| Organization selection | One or all organizations at personal sign-in; key's organization for API keys |
| App views and reply confirmation | Personal OAuth required |
What you're looking at
Open Settings → Connections → Developer access → MCP in Sift. Copy the server URL from your environment. The public URL is a connection address, not a password. Your OAuth token or API key is the credential. Keep credentials out of messages, screenshots, and repositories.
Connect with personal OAuth
- Add a remote MCP server in your client's connector settings.
- Name the connection
Sift. - Set its URL to
https://mcp.getsift.ai/mcp. - Choose OAuth if the client asks for authentication.
- Complete Sift sign-in. Select one organization, or All organizations.
- Fetch the tool list and call
list_skillswith an empty object. - Make a small authorized read before a larger task.
Use a client that supports remote Streamable HTTP and Sift's OAuth flow. Client names and connector menus can change. The Sift MCP tab contains client setup guides. A client that supports only local process servers needs a compatible remote connection method.
The server supports dynamic client registration and PKCE with S256.
Authorization codes expire after five minutes. Access tokens expire after 90 days.
There is no refresh-token flow. If the token expires, repeat sign-in.
Use several organizations
If you select All organizations at sign-in, one connection reaches every organization you belong to. It works like a default profile with an optional override:
| Tool or argument | What it does |
|---|---|
list_orgs | Lists your organizations and marks the active one. |
switch_org | Makes another organization active for this connection. |
org on a tool call | Runs that call in the named organization. The active organization does not change. |
A new all-organizations connection has no active organization. Call switch_org, or pass org, before the first data call.
Every call runs in exactly one organization. Each result starts with the organization's name and id.
Each call checks your membership and MCP access in that organization.
The active organization belongs to the connection. If several chats share one connection, a switch in one chat applies to all of them.
If you select one organization, the connection works as before. To reach other organizations, connect again and select All organizations.
Connect with an API key
Use this method for an unattended integration that does not need a personal identity:
| Connection field | Value |
|---|---|
| Name | A label such as Sift reporting |
| URL | https://mcp.getsift.ai/mcp |
| Transport | HTTP / Streamable HTTP |
| Header name | Authorization |
| Header value | Bearer <SIFT_API_KEY> |
Store the key in the client's secret store or environment. Do not paste it into an agent prompt.
MCP uses a bearer header. The REST API uses X-API-Key; these are different connection settings.
The key fixes the organization. It supplies no personal user identity. Organization defaults must allow MCP access. Keys cannot use personal app tools, Events, or reply confirmation. Some operations require a person even when a key can connect. Each operation still checks its own access rules.
Understand access fields
Super admins set organization controls in the MCP tab. The same controls apply to the sift CLI, which connects through the MCP server:
| Field | Meaning |
|---|---|
blocked | Blocks MCP for the organization. Overrides all person and role grants. |
sendBlocked | Blocks sending through MCP. Other permitted MCP work can continue. |
defaultAccess | Default permission to use MCP. Organization keys require this to be allowed. |
defaultSend | Default permission to send through MCP. Human confirmation still applies. |
Roles grant Use MCP and Send through MCP in People & access.
User overrides use Inherit, Allow, or Block for each capability.
A user block overrides a role grant. Organization blocks override all grants.
Effective results use useMcp and sendMcp. These report allowed access, not a promise of delivery.
New organizations default to no MCP access. Sending defaults off. Saving an organization or user control changes the effective policy. An unsaved toggle does not change access. MCP never expands queue access or sending account access.
Inspect your personal connections
When execute is available, inspect the contract first:
return await sift.spec("config.mcpConnection.list")Then list your authorizations:
const result = await sift.call("config.mcpConnection.list", { limit: 20 })
return result| Input | Type and behavior |
|---|---|
cursor | Optional string. Use the previous nextCursor. Omit for the first page. |
limit | Optional integer, 1–100. Default 50. |
The list returns items, total, and nextCursor. It includes expired and revoked connections.
It returns no bearer tokens.
| Connection field | Meaning |
|---|---|
id | Connection identifier. Use this for revocation. |
clientId | Registered OAuth client identifier. |
createdAt | When the authorization was created. |
expiresAt | When the authorization expires. |
revokedAt | When it was revoked; null if it has not been revoked. |
type | mcpConnection on list items. |
name | The client identifier used as the list label. |
url, parent | null on connection list items. |
To revoke a connection, read config.mcpConnection.delete and call it with id only.
Revoke only the connection the user requests. Its access tokens stop working on the next request.
Repeated revocation returns the original receipt. Revoking the current connection can end your own access.
Troubleshoot a connection
| Symptom | Next step |
|---|---|
Authentication fails or returns 401 | Check the header or repeat personal sign-in. Check token expiry and revocation. |
Access returns 403 | Check organization blocks, effective user grants, and the operation's required permission. |
execute cannot run | Check dashboard access and the caller's available tool set. |
| Listening cannot run | Check personal OAuth and the organization's Listening feature. |
A legacy session returns 404 | Initialize again and resume with your saved cursor. Preserve routing cookies. |
| Fields differ from a cached tool list | Reconnect or refresh the server in your MCP gateway. |
| Confirmation cannot render | Use the authenticated Sift link. Opening the link does not approve. |
| An app view cannot render | Use its text, structured result, or Sift link. |
Sift records the caller, client, tool input, timing, outcome, and response size for audits. Response content is not logged by the MCP tool-call audit. Ask support for an organization access review.
Tips
- Use one API key per integration.
- Verify the organization before each task.
- Keep separate connections for separate environments.
- Treat
userIdas a compatibility field, not an identity override.