Skip to main content
skill CX Codex

mcp-oauth — Claude Code skill: OAuth 2.1 sign-in for MCP servers

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.

no license 21 installs ★ 1 updated 2026-02-14

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add clavia-labs/skills --skill mcp-oauth -a claude-code
Open on GitHub

What mcp-oauth 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.

What it helps with

  • 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 for the agent

  • 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.

How to install mcp-oauth

1Skills CLI (Vercel)

npx skills add clavia-labs/skills --skill mcp-oauth -a claude-code

2Manually: put the files in place

~/.claude/skills/mcp-oauth/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/mcp-oauth/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about mcp-oauth

How do I install mcp-oauth in Claude Code?

Run npx skills add clavia-labs/skills --skill mcp-oauth -a claude-code. The skill lands at ~/.claude/skills/mcp-oauth/SKILL.md.

What does mcp-oauth do?

It carries an agent from the first metadata request all the way to a working MCP session: client registration, the localhost callback, the token exchange, then tool calls on the server.

Does every MCP server support the registration step?

No. When the registration endpoint answers 404, the skill asks you for a client_id and carries on with that value.

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set2

Project sponsors

Companies that keep this analytics open