Connect OAuth for MCP tools

Wire **Settings → Connected Accounts** so tool policies that use **`oauth`** sources resolve **your** GitHub (or other provider) token — per-user MCP calls instead of one shared PAT sitting unused in a static field.

Plus: three Admin Agent prompts you can paste — decode a failed tool call that asks the user to connect their account, audit OAuth provider rows vs policy env vars, and draft a rollout note separating **Linked Accounts** (Slack/Discord bots) from **Connected Accounts** (MCP OAuth).

Audience	Everyone · Admins · Developers
Time	~7 min
Prerequisites	A tool policy exists with at least one MCP server that can use `oauth` sources ([Define a tool policy](/tutorials/define-a-tool-policy), [Add an MCP server](/tutorials/add-an-mcp-server)). Org admins can configure OAuth Providers (client ID + secret). End users need permission to open Settings on their own login.
You'll end up with	Working Connected Accounts row for the provider your MCP needs — tool calls stop failing with connect account prompts — plus the vocabulary to explain that Linked Accounts ([Link your chat apps to your Auxot account](/tutorials/link-your-chat-apps-to-your-auxot-account)) handles chat identity, not MCP OAuth.

When a tutorial shows italic text in quotation marks, it usually mirrors a label or helper string inside Auxot. Product copy changes between releases — if something reads differently in your workspace, trust what you see on screen.

Callouts with a Worth knowing gold accent are meant as must-read context before you move on. Blockquotes that open with Tip are lighter, optional depth.

Why this matters

Some MCP servers are authored for per-user credentials, especially GitHub: Alice’s issues aren’t Bob’s repos. Auxot’s answer is the oauth env-var source on the tool policy: at runtime the tools worker pulls the calling user’s OAuth access token, refreshes it if needed, and injects it into the MCP subprocess (Tool Worker Policies).

That only works after two halves exist:

Org admin registers the OAuth app under Settings → OAuth Providers (client ID + secret for that vendor).
Each human completes Settings → Connected Accounts for the same provider (GitHub, Google, Slack, etc.), whichever the policy references.

Until step 2 finishes for you, tool calls backed by oauth fail with guidance to connect the account. The model isn’t broken; the token is missing.

Different label, different job: Linked Accounts proves who you are to Slack/Discord bots (Link your chat apps to your Auxot account). Connected Accounts stores OAuth grants for MCP. They sit near each other in the Settings sidebar, but they aren’t interchangeable.

Tokens don’t refresh on their own. You connect once per provider per Auxot user that needs the tool.

Quick start

Admins (once per org + provider)

Register the vendor OAuth app: create the app in GitHub/Google/etc. per their docs, using the callback URLs Auxot shows or documents.
Open Auxot Settings → OAuth Providers: add the provider and paste its client ID and secret (Tool Worker Policies).
Wire the tool policy: set the MCP server env var (e.g. GITHUB_TOKEN) to source oauth with the provider slug you configured (the manual walkthrough uses github).

End users (each person who runs the tool)

Open Settings → Connected Accounts.
Connect the provider (GitHub, …): complete browser OAuth consent.
Retry the agent/tool flow: the worker now resolves your token.

Done? The chat tool call succeeds where it previously asked you to connect, and Audit Logs entries about missing tokens stop appearing.

The agent can do that?

1. Decode “connect your account” failures

Paste (redact tokens) into Admin Agent:

Agent tool call failed with message about connecting [provider]. Tool policy uses oauth for GITHUB_TOKEN. User says they're logged into Auxot. Ordered checklist: Connected Accounts vs wrong org vs revoked OAuth vs policy typo — bullets only.

Why it’s non-obvious: Auxot session ≠ vendor OAuth grant; Admin Agent separates layers after you paste the error text.

2. Admin wiring audit before widening a pilot

List checks an admin should verify before rolling GitHub MCP oauth to 20 people: OAuth provider row, callback URLs, policy env names, and token scopes implied by MCP package README — nothing end-user facing — markdown bullets.

Why it’s non-obvious: Scope gaps surface only when the fifth user hits a forbidden endpoint. Catching them up front beats paging the on-call later.

3. Linked vs Connected announcement

Draft a `#engineering` blurb: Linked Accounts = Slack/Discord identity; Connected Accounts = OAuth for MCP tools. Both under Settings, both self-service. Under 120 words.

Why it’s non-obvious: Teams mix the labels in hallway conversation; one note saves duplicate IT tickets.

Go deeper

GitHub MCP example (from manual)

Configure GitHub OAuth app in Auxot (Settings → OAuth Providers).
Tool policy: GitHub MCP server, GITHUB_TOKEN → oauth, provider github.
Users connect GitHub under Settings → Connected Accounts.
Runtime: worker injects user token into MCP (Tool Worker Policies).

Shared PAT fallback

org_secret, team_secret, or user_secret still work; you trade per-user scopes for operational simplicity (Manage your Credentials). Pick oauth when audits demand least-privilege per human.

Encryption

OAuth tokens rest encrypted like other secrets; worker decrypts in memory only (Tool Worker Policies).

Quick contrast table

Settings page	Solves
Linked Accounts	Slack/Discord identity for bots (Link your chat apps to your Auxot account)
Connected Accounts	Vendor OAuth for MCP tool runtime
OAuth Providers (admin)	Registers client IDs/secrets Auxot uses during OAuth flows

Walkthrough

Step 1: Confirm policy actually uses `oauth`

Open Settings → Tool Policies → [policy] → MCP server. Env rows should show source oauth; if everything is static, OAuth connection won’t help until policy changes (Add an MCP server).

Step 2: Admin registers provider

Settings → OAuth Providers: complete provider-specific fields; fix callback mismatch errors using both vendor and Auxot docs (Tool Worker Policies).

Step 3: User connects

Step 4: Smoke-test tool call

Same chat prompt that previously failed; expect MCP-backed behavior (e.g. repo call). If still failing, verify same Auxot org, provider slug spelling, and whether admins revoked old grants.

Step 5: Document internal expectation

Add one sentence to your agent directory or onboarding: “GitHub MCP requires Connected Accounts; Linked Accounts alone isn’t enough.”

What’s next

→ Back up and export your Auxot data. OAuth apps, grants, and audit pulls belong in the same continuity runbook once tooling goes live.
→ Add an MCP server. Catalog vs manual MCP rows and oauth source selection.
→ Define a tool policy. Which agents inherit OAuth-backed tools.
→ Link your chat apps to your Auxot account. Slack/Discord verification flows (Linked Accounts).
→ Manage your Credentials. When PATs and secrets beat OAuth for your threat model.
→ Tool Worker Policies. Credential sources table and the OAuth-backed MCP section.

Reference

Pages in Auxot: Settings → Connected Accounts, Settings → OAuth Providers (admin), Settings → Tool Policies
Manual: Tool Worker Policies
See also: Back up and export your Auxot data, Run the tools worker (auxot-tools), Rotate credentials without surprising your agents