MCP Auth & OAuth Setup

Start From The App Detail

  1. Open Apps and select the service.
  2. Read the authentication choices shown for that provider.
  3. Use OAuth when it is offered.
  4. Add a key or manual credential only when the provider requires it.
  5. Return to the app detail and confirm the connected state.

Searchable app picker for choosing a provider

This guide explains how app connections work in Neotask, which setup path applies to each provider, and how to complete high-friction OAuth and credential flows step by step.

Start With The Setup Mode

Every app in Neotask falls into one of these setup modes:

  1. Managed OAuth
  2. Manual OAuth
  3. API key
  4. Manual credentials
  5. Custom URL first
  6. No auth or local runtime

Do not start with generic reconnect advice until you know which mode the provider actually uses.

Managed OAuth

Use this when the provider supports a direct Neotask-led OAuth flow.

Step-by-Step

  1. Open the provider in the Apps tab.
  2. Click Connect.
  3. Complete the browser-based consent flow.
  4. Return to Neotask.
  5. Confirm the provider moves to connected.

Return to Apps and verify that the provider appears in the connected group before testing an agent request.

Connected app catalog after authorization

If the flow fails repeatedly and the provider is known to be managed_dcr_broken, stop retrying the same path and move to the documented fallback.

Important Surface Rule

For MCP providers, the auth flow lives in Apps, not the Google Workspace Integrations surface.

Examples that belong in Apps even when they use OAuth:

Manual OAuth

Use this when the provider needs an app registration or pre-registered OAuth app first.

Step-by-Step

  1. Open the provider card in Neotask.
  2. Copy the exact callback URL shown there.
  3. Open the provider developer portal.
  4. Create or open the OAuth app.
  5. Add the callback URL exactly.
  6. Add the required scopes exactly.
  7. Copy the clientId.
  8. Copy the clientSecret if the provider uses one.
  9. Paste the values into Neotask.
  10. Start the connection flow and approve access.

Important Callback Rule

The callback host often points at the Neotask MCP auth service. That is expected. Use the exact callback URL from Neotask rather than inventing your own redirect URL.

API Key

Use this when the provider only needs an API key or token.

Step-by-Step

  1. Create or copy the API key from the provider.
  2. Open the provider card in Neotask.
  3. Paste the key into the required field.
  4. Save the connection.
  5. Re-test the provider.

Manual Credentials

Use this when the provider needs structured credentials such as baseUrl, instanceUrl, account IDs, token IDs, or tenant-specific hosts.

Step-by-Step

  1. Gather every required field before saving.
  2. Confirm the correct instance or tenant URL.
  3. Paste each value exactly.
  4. Save the connection.
  5. Re-test the provider.

If a provider needs manual credentials, do not switch the caller into OAuth unless the provider card explicitly says to do so.

Custom URL First

Some providers cannot be validated until the caller saves the correct instance URL first.

Support Rule

If the provider asks for baseUrl, instanceUrl, workspaceUrl, organizationUrl, or another tenant-specific URL, confirm that value before discussing OAuth.

High-Value Examples

  1. Benchling Use the correct tenant-specific Benchling URL before saving the API key.
  2. Visier Use the correct vanity or tenant URL before saving credentials.
  3. NetSuite Use the correct account-specific host and account ID.

No Auth Or Local Runtime

Some providers do not behave like cloud-hosted OAuth services.

JetBrains

JetBrains depends on a local IDE and plugin path. If the supported IDE is not open, or the plugin/runtime is not active, tools can be unavailable even though the product surface looks fine.

Support Rule

Do not force no-auth or local-runtime providers into OAuth troubleshooting.

Provider Playbooks

These are the highest-friction OAuth flows that support should know cold.

Slack

  1. Create a Slack app from scratch in the Slack developer portal.
  2. Add the exact Neotask callback URL to Slack.
  3. Add the required user scopes shown by Neotask.
  4. Copy the Client ID and Client Secret.
  5. Paste them into Neotask and reconnect.

Figma

  1. Create the Figma app in the Figma developer portal.
  2. Add the exact Neotask callback URL.
  3. Request the mcp:connect scope.
  4. Copy the Client ID and Client Secret.
  5. Paste them into Neotask and reconnect.

Figma is sensitive to the exact app type and the restricted MCP scope.

Airtable

  1. Register the Airtable OAuth integration.
  2. Add the exact Neotask callback URL.
  3. Add the required Airtable data, schema, webhook, and user-email scopes shown by Neotask.
  4. Copy the Client ID and Client Secret.
  5. Paste them into Neotask and reconnect.

Box

  1. Create a custom Box app with OAuth 2.0 user authentication.
  2. Add the exact Neotask callback URL.
  3. Enable the required Box application scopes.
  4. Copy the Client ID and Client Secret.
  5. Paste them into Neotask and reconnect.

Canva

  1. Create the Canva integration.
  2. Add the exact Neotask callback URL.
  3. Copy the Client ID and Client Secret.
  4. Paste them into Neotask and reconnect.

monday.com

  1. Create the monday.com app.
  2. Add the exact Neotask callback URL.
  3. Copy the Client ID and Client Secret.
  4. Paste them into Neotask and reconnect.

Asana

  1. Create the Asana app in the developer console.
  2. Add the exact Neotask callback URL.
  3. Copy the Client ID and Client Secret.
  4. Paste them into Neotask and reconnect.

Do not improvise extra scopes for Asana if the product truth says the provider does not use them.

Salesforce

  1. Open Salesforce App Manager and create or edit the Connected App.
  2. Enable OAuth settings.
  3. Paste the exact Neotask callback URL.
  4. Add the required API and refresh scopes.
  5. Copy the Consumer Key and Consumer Secret.
  6. Paste them into Neotask and reconnect.

Microsoft Family

Use this pattern for Microsoft Teams, Microsoft 365, Azure, Azure DevOps, and PowerBI:

  1. Open Microsoft Entra.
  2. Create or open the app registration.
  3. Add the exact Neotask callback URL as a Web redirect URI.
  4. Copy the Application (client) ID.
  5. Create or copy the client secret if required.
  6. Paste those values into Neotask.
  7. Re-run consent in the correct Microsoft tenant.

Connected But Tools Still Fail

If auth looks healthy but tools still fail, check this order:

  1. Wrong scope.
  2. Wrong workspace or provider account.
  3. Missing scopes.
  4. Wrong custom URL or instance URL.
  5. Local runtime or plugin not active.
  6. Company flow using a tenant connection, or tenant flow using a company connection.

For a dedicated runbook, use Support MCP Scope And Runtime.

When To Stop And Ask Support

Escalate when:

  1. The callback URL in Neotask matches the provider portal, but the provider still rejects it.
  2. The provider is marked managed_dcr_broken or unreachable.
  3. The provider is connected in one scope and still fails in another.
  4. The flow requires company-specific or admin-specific guidance that is not on the provider card.