# mcp-oauth

Walks an agent through an OAuth 2.1 sign-in to an MCP server: discovery, PKCE, a local callback, token exchange and the first tool call.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 21 installs · ★ 1 repo stars
- Author: clavia-labs
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/clavia-labs/skills/tree/HEAD/mcp-oauth/SKILL.md
- Updated: 2026-02-14
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/mcp-oauth

## What it does

This skill takes an agent through signing in to an MCP server that sits behind OAuth 2.1. It reads the metadata for the protected resource and the authorization server, registers a client, then builds an authorization link with a PKCE challenge. Your browser opens on its own; a listener on port 9999 grabs the redirect code and drops it into `/tmp/mcp_oauth_code.txt`.

From there it trades the code for a token and opens an MCP session. It asks for `tools/list`, then can call one of the tools. A 401 with a refresh token on hand gets a quiet refresh and a retry. Everything runs on `curl` plus two bundled Node.js scripts, `scripts/pkce.js` and `scripts/callback_server.js`.

Port 9999 has to be free or the callback listener never starts — the troubleshooting notes offer `lsof -ti:9999 | xargs kill -9` for whatever is holding it. When a server has no dynamic registration endpoint, you get asked for a `client_id` and the flow continues with it.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add clavia-labs/skills --skill mcp-oauth -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/mcp-oauth/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/mcp-oauth/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add clavia-labs/skills --skill mcp-oauth -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/mcp-oauth/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add clavia-labs/skills --skill mcp-oauth -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/mcp-oauth/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install clavia-labs/skills mcp-oauth
```

2. **Manually: put the files in place**
- File: `.github/skills/mcp-oauth/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add clavia-labs/skills --skill mcp-oauth -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/clavia-labs/skills --path mcp-oauth
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/mcp-oauth/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add clavia-labs/skills --skill mcp-oauth -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/clavia-labs/skills/tree/HEAD/mcp-oauth/SKILL.md

## When to use it
- sign in to an OAuth-protected MCP server and get a usable token
- trace a 401 or `invalid_token` answer back to its cause
- catch the redirect code on localhost without pasting it by hand
- see which tools a third-party MCP server exposes
- refresh an expired token and retry the call

## Example prompts
- Authenticate against the MCP server at `MCP_SERVER_URL` and list its tools.
- The token expired and the server returned 401 — refresh it and retry.
- Call the `<tool_name>` tool with empty arguments.

## Similar
- [oauth-oidc-misconfiguration](https://affpapa.org/en/nevibecode/skills/oauth-oidc-misconfiguration.md) — skill · 4100 installs
- [oauth-implementation](https://affpapa.org/en/nevibecode/skills/oauth-implementation.md) — skill · 768 installs
- [oauth-oidc-expert](https://affpapa.org/en/nevibecode/agents/oauth-oidc-expert.md) — subagent · ★ 1029 repo stars
- [oauth](https://affpapa.org/en/nevibecode/skills/mcollina-oauth.md) — skill · 1400 installs
- [openrouter-oauth](https://affpapa.org/en/nevibecode/skills/openrouter-oauth.md) — skill · 362 installs
- [oauth-oidc-implementer](https://affpapa.org/en/nevibecode/skills/oauth-oidc-implementer.md) — skill · 183 installs

From the same set: [clavia-labs/skills](https://affpapa.org/en/nevibecode/by/clavia-labs/skills.md) — 2 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
