Skip to main content
Documentation

Adapts MCP

A lightweight MCP (Model Context Protocol) stdio bridge that connects AI coding assistants to Adapts MCP. Works with any MCP-compatible host — Cursor, Claude Desktop, Claude Code, Windsurf, and more.

Prerequisites

  • Python 3.9+ — Download Python if you don't have it installed. Verify with:
python3 --version

Installation

Download mcp-client.pyz from the latest release. No additional dependencies required.

Quick Start

Cursor

Add to your Cursor MCP settings (.cursor/mcp.json in your project or global config):

{
  "mcpServers": {
    "adapts-mcp": {
      "command": "python3",
      "args": ["/path/to/mcp-client.pyz"]
    }
  }
}
Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "adapts-mcp": {
      "command": "python3",
      "args": ["/path/to/mcp-client.pyz"]
    }
  }
}
Claude Code 
claude mcp add adapts-mcp -- python3 /path/to/mcp-client.pyz
Windsurf

Add to your Windsurf MCP config:

{
  "mcpServers": {
    "adapts-mcp": {
      "command": "python3",
      "args": ["/path/to/mcp-client.pyz"]
    }
  }
}

Authentication

On first run, the bridge opens your browser to sign in with Google or Microsoft. Your token is stored locally and refreshed automatically. No AWS credentials needed.

If the auth flow doesn't trigger automatically, run it manually:

python3 /path/to/mcp-client.pyz auth

To force a fresh login (clears existing token):

python3 /path/to/mcp-client.pyz auth --force

For headless environments (SSH, containers), the auth URL is printed to stderr — open it in any browser to complete sign-in.

Agent Skills

What is a skill? A small markdown file that teaches your AI assistant how to use the Adapts tools — which tools are available, how to chain them, and which models to pick.

Cursor

1. Install the skill file

mkdir -p ~/.cursor/skills/adapts-assistant
mv ~/Downloads/adapts-assistant.md ~/.cursor/skills/adapts-assistant/SKILL.md

2. Use it in a prompt

Reference the skill with /adapts-assistant in your prompt:

/adapts-assistant show me the class hierarchy in the PromptService package

/adapts-assistant what classes import S3DiskCache, and trace how flush_to_disk is called across the org?

/adapts-assistant chat with the code_cache wiki — how does the background indexer rebuild references?
Claude Code

1. Add to your CLAUDE.md

mkdir -p ~/.claude
cat ~/Downloads/adapts-assistant.md >> ~/.claude/CLAUDE.md

Or add it to a project-level CLAUDE.md at the root of your repository for per-project setup.

2. Use it in a prompt

Claude Code reads CLAUDE.md automatically. Just ask:

find all callers of persist_class_data across the organization

chat with the adapts_app wiki — how does authentication work?
Windsurf

1. Install the rule file

mkdir -p ~/.windsurf/rules
mv ~/Downloads/adapts-assistant.md ~/.windsurf/rules/adapts-assistant.md

Or add it as a project-level rule at .windsurf/rules/adapts-assistant.md in your repository.

2. Use it in a prompt

Windsurf picks up rules automatically. Just ask:

get the source code for the parse_repository function in code_cache

browse the wiki pages for PromptService and summarize the API design
How it works

The skill file is intentionally minimal. Instead of listing every tool and parameter, it points to a live resource on the Adapts MCP server:

FetchMcpResource  server=user-adapts-mcp  uri=codecache://docs/guide

When your agent reads the skill, it fetches the guide dynamically. This means:

  • New tools added to the server appear automatically
  • Updated docs are always in sync with the deployed version
  • No maintenance — the skill file never goes stale

The guide includes tool reference tables, recommended workflows, model selection tips, and debugging commands.

Troubleshooting

Check your version

python3 /path/to/mcp-client.pyz --version

Authentication issues

  • Auth doesn't trigger — Run auth manually:
python3 /path/to/mcp-client.pyz auth
  • 401 / token errors — Force a fresh login, then restart your MCP host:
python3 /path/to/mcp-client.pyz auth --force
  • "Could not open a browser" — You're in a headless environment. Copy the URL printed to stderr and open it in any browser.
  • Auth timeout — Ensure no firewall is blocking localhost ports 43123–43172. The sign-in must complete within 5 minutes.

Other issues

  • "UPDATE REQUIRED" — Your version is below the minimum. Download the latest .pyz from adapts.app.
  • Connection timeouts — Check your network and try running the doctor command:
python3 /path/to/mcp-client.pyz doctor

Support

For questions or issues, contact dev@adapts.ai.