# MCP connections (/docs/developer/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 [#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 ` | | 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 [#what-youre-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 [#connect-with-personal-oauth] 1. Add a remote MCP server in your client's connector settings. 2. Name the connection `Sift`. 3. Set its URL to `https://mcp.getsift.ai/mcp`. 4. Choose OAuth if the client asks for authentication. 5. Complete Sift sign-in. Select one organization, or **All organizations**. 6. Fetch the tool list and call `list_skills` with an empty object. 7. 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 [#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 [#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 ` | 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 [#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 [#inspect-your-personal-connections] When `execute` is available, inspect the contract first: ```js return await sift.spec("config.mcpConnection.list") ``` Then list your authorizations: ```js 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 [#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 [#tips] - Use one API key per integration. - Verify the organization before each task. - Keep separate connections for separate environments. - Treat `userId` as a compatibility field, not an identity override. ## Related [#related] Start useful work after connecting. Build requests from exact fields. Manage service credentials.