platform-2step-mcp 0.14.0

MCP server for Platform-2Step API with human-in-the-loop confirmation

Platform-2Step MCP

MCP server that enables AI agents (Claude, GPT, etc.) to interact with AgendaPro's Platform API safely through a human-in-the-loop confirmation system.

All mutations require human confirmation — the AI agent can only create pending operations, never execute them directly.

Prerequisites

• Python 3.11+ — check with python3 --version
• uv (recommended) — Python package manager

Install uv

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
irm https://astral.sh/uv/install.ps1 | iex

After installing, restart your terminal or run source ~/.bashrc (or ~/.zshrc).

Quick Setup (recommended)

The fastest way to configure the MCP for Claude Code and/or Cursor:

uvx --from platform-2step-mcp platform-mcp-setup

Run without flags and the CLI asks two questions:

1. Which client? — Claude Code, Cursor, or both.
2. Which scope? — user (global) or project (shareable via git).

The environment is never interactive: it defaults to production. Pass --env staging to override.

Example interactive run:

¿Qué cliente querés configurar?
  [1] Claude Code (default)
  [2] Cursor
  [3] Ambos
> 2

¿Alcance de la configuración?
  [1] Usuario (global, todos los proyectos) (default)
  [2] Proyecto (solo este directorio, compartible vía git)
> 1

Non-interactive usage (flags)

Pass --client and --scope explicitly to skip the prompts — useful for automation, CI, and docs:

# Claude Code, user scope (the legacy default)
uvx --from platform-2step-mcp platform-mcp-setup --client claude --scope user

# Cursor, user scope
uvx --from platform-2step-mcp platform-mcp-setup --client cursor --scope user

# Both clients, project scope, staging env
uvx --from platform-2step-mcp platform-mcp-setup --client both --scope project --env staging

Pass --yes (or -y) to force non-interactive mode with defaults (claude, user) when a flag is missing.

What the setup writes

Client	User scope	Project scope
Claude Code	~/.claude.json	<cwd>/.mcp.json
Cursor	~/.cursor/mcp.json	<cwd>/.cursor/mcp.json

The setup:

• Preserves all existing top-level keys and other MCP servers in each file (never clobbers your other config).
• Is idempotent — running it again updates the entry without breaking anything.
• Installs bundled skills (see below) unless you pass --skip-skills.

Skills

The setup installs bundled skills (e.g. agendapro-login) into ~/.claude/skills/. Cursor reads that directory automatically via its Claude-compat mode, so the same skills work for both clients without duplication — no copying required.

Note: uvx downloads and runs the package from PyPI automatically — no manual install needed.

Authentication

Before using the MCP, you must authenticate once. The MCP uses OAuth 2.0 Device Flow — your browser opens automatically and you click "Authorize".

# Production
PLATFORM_2STEPS_BFF_URL=https://ap-api.agendapro.com/platform-2steps-bff \
  uvx --from platform-2step-mcp platform-mcp-auth login

# Staging
PLATFORM_2STEPS_BFF_URL=https://ap-api.agendaprodev.com/platform-2steps-bff \
  uvx --from platform-2step-mcp platform-mcp-auth login

You'll see:

============================================================
AUTENTICACIÓN REQUERIDA
============================================================

Abriendo navegador... Tu código es: ABCD-1234

Esperando autenticación en el navegador...
Expira en 10 minutos.
============================================================

¡Autenticación exitosa!

Tokens are cached at ~/.platform-mcp/tokens.json and reused automatically.

Auth CLI commands

Command	Description
platform-mcp-auth login	Authenticate (interactive)
platform-mcp-auth login --force	Re-authenticate even if tokens are valid
platform-mcp-auth status	Check if tokens are valid
platform-mcp-auth logout	Clear cached tokens

Important: Always set PLATFORM_2STEPS_BFF_URL before running auth commands.

Setup CLI commands

Command	Description
platform-mcp-setup	Interactive: asks for client and scope, uses production env
platform-mcp-setup --client claude	Configure only Claude Code (skips the client prompt)
platform-mcp-setup --client cursor	Configure only Cursor
platform-mcp-setup --client both	Configure Claude Code and Cursor at the same scope
platform-mcp-setup --scope project	Project scope (skips the scope prompt)
platform-mcp-setup --env staging	Use the staging environment
platform-mcp-setup --yes	Non-interactive: use defaults (claude, user) for missing flags
platform-mcp-setup --skip-skills	Don't install bundled skills
platform-mcp-setup --force	Recreate config if the JSON file is corrupted

Manual Configuration

If you prefer to configure manually instead of using platform-mcp-setup:

Claude Code (user scope — global)

Edit ~/.claude.json and add the entry under mcpServers at the root level (preserve all other top-level keys):

{
  "mcpServers": {
    "platform-2step": {
      "command": "uvx",
      "args": ["platform-2step-mcp"],
      "env": {
        "PLATFORM_2STEPS_BFF_URL": "https://ap-api.agendapro.com/platform-2steps-bff",
        "API_HOST_PUBLIC": "mcp.agendapro.com"
      }
    }
  }
}

Warning: ~/.claude.json contains your full Claude Code state (theme, sessions, project state, OAuth tokens). Use platform-mcp-setup instead of editing manually to avoid corruption.

Claude Code (project scope — shareable via git)

Create .mcp.json in your project root:

{
  "mcpServers": {
    "platform-2step": {
      "command": "uvx",
      "args": ["platform-2step-mcp"],
      "env": {
        "PLATFORM_2STEPS_BFF_URL": "https://ap-api.agendapro.com/platform-2steps-bff",
        "API_HOST_PUBLIC": "mcp.agendapro.com"
      }
    }
  }
}

Claude Desktop

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

{
  "mcpServers": {
    "platform-2step": {
      "command": "uvx",
      "args": ["platform-2step-mcp"],
      "env": {
        "PLATFORM_2STEPS_BFF_URL": "https://ap-api.agendapro.com/platform-2steps-bff",
        "API_HOST_PUBLIC": "mcp.agendapro.com"
      }
    }
  }
}

Cursor

Cursor reads MCP servers from two locations:

• ~/.cursor/mcp.json — user scope, available in every project.
• .cursor/mcp.json in your project root — project scope, shareable via git.

You can configure either via Settings > MCP in the Cursor UI, or by editing the file directly:

{
  "mcpServers": {
    "platform-2step": {
      "command": "uvx",
      "args": ["platform-2step-mcp"],
      "env": {
        "PLATFORM_2STEPS_BFF_URL": "https://ap-api.agendapro.com/platform-2steps-bff",
        "API_HOST_PUBLIC": "mcp.agendapro.com"
      }
    }
  }
}

Skills in Cursor: Cursor auto-discovers skills from ~/.cursor/skills/, .cursor/skills/, and — for compatibility — from ~/.claude/skills/ and .claude/skills/. The skills bundled with platform-mcp-setup live in ~/.claude/skills/, so Cursor loads them automatically without any extra copy step.

Using Multiple Environments

To use both staging and production simultaneously, configure separate token paths:

{
  "mcpServers": {
    "platform-2step-staging": {
      "command": "uvx",
      "args": ["platform-2step-mcp"],
      "env": {
        "PLATFORM_2STEPS_BFF_URL": "https://ap-api.agendaprodev.com/platform-2steps-bff",
        "API_HOST_PUBLIC": "mcp.agendaprodev.com",
        "PLATFORM_MCP_TOKEN_PATH": "~/.platform-mcp/tokens-staging.json"
      }
    },
    "platform-2step-prod": {
      "command": "uvx",
      "args": ["platform-2step-mcp"],
      "env": {
        "PLATFORM_2STEPS_BFF_URL": "https://ap-api.agendapro.com/platform-2steps-bff",
        "API_HOST_PUBLIC": "mcp.agendapro.com",
        "PLATFORM_MCP_TOKEN_PATH": "~/.platform-mcp/tokens-prod.json"
      }
    }
  }
}

Authenticate each environment separately:

# Staging
PLATFORM_2STEPS_BFF_URL=https://ap-api.agendaprodev.com/platform-2steps-bff \
PLATFORM_MCP_TOKEN_PATH=~/.platform-mcp/tokens-staging.json \
uvx --from platform-2step-mcp platform-mcp-auth login

# Production
PLATFORM_2STEPS_BFF_URL=https://ap-api.agendapro.com/platform-2steps-bff \
PLATFORM_MCP_TOKEN_PATH=~/.platform-mcp/tokens-prod.json \
uvx --from platform-2step-mcp platform-mcp-auth login

Available Tools

Once connected, the MCP provides these tools to the AI agent:

Read (no confirmation needed)

• Categories: list_categories, get_category
• Services: list_services, get_service
• Bookings: list_bookings, get_booking
• Locations: list_locations, get_location
• Providers: list_providers, get_provider
• Memberships: list_memberships, get_membership
• Clients: list_clients, get_client
• Users: get_user
• Custom Attributes: list_custom_attributes

Mutations (require human confirmation)

• Batch operations: create_batch — creates up to 50 operations (create, update, delete) that must be confirmed by the user in the AgendaPro frontend

Analytics (read-only SQL)

• query_analytics_db — execute SQL against synced analytics data
• get_analytics_status — check data sync status
• refresh_analytics_data — trigger data refresh

Troubleshooting

"Not authenticated" error

Error: Not authenticated. Run 'platform-mcp-auth login' first.

Your tokens expired or were never created. Run:

PLATFORM_2STEPS_BFF_URL=https://ap-api.agendapro.com/platform-2steps-bff \
  uvx --from platform-2step-mcp platform-mcp-auth login

"Configuration error: PLATFORM_2STEPS_BFF_URL is required"

The environment variable is not set. Make sure it's in your ~/.claude.json (Claude Code, user scope) config under mcpServers.platform-2step.env, or run platform-mcp-setup to configure it automatically.

MCP tools not showing in Claude

1. Check the MCP server is running: look for errors in Claude Code's MCP logs
2. Verify auth: PLATFORM_2STEPS_BFF_URL=https://ap-api.agendapro.com/platform-2steps-bff uvx --from platform-2step-mcp platform-mcp-auth status
3. Restart Claude Code after config changes

"uvx: command not found"

Install uv first (see Prerequisites).

JSON parse error when running platform-mcp-setup

If your ~/.claude.json has invalid JSON, use --force to recreate it:

uvx --from platform-2step-mcp platform-mcp-setup --force

Warning: --force recreates the file. All other Claude Code state (theme, sessions, project state, other MCP servers) in the corrupted file will be lost. Back up ~/.claude.json first if possible.

Environment Variables

Variable	Required	Default	Description
PLATFORM_2STEPS_BFF_URL	Yes	—	BFF URL for API integration (staging or production)
API_HOST_PUBLIC	No	Falls back to PLATFORM_2STEPS_BFF_URL	Public hostname for browser-facing URLs (e.g., mcp.agendapro.com)
PLATFORM_MCP_TOKEN_PATH	No	~/.platform-mcp/tokens.json	Token storage location
LOG_LEVEL	No	INFO	Logging level (DEBUG, INFO, WARNING, ERROR)
DEBUG_HTTP	No	false	Enable cURL-style HTTP request/response logging

Documentation

For comprehensive documentation including architecture, security, and development guides, see CLAUDE.md.

License

MIT