platform-2step-mcp 0.13.1

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:

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

This command:

• Creates or updates ~/.claude.json with the production server config (user scope — global, available in all projects)
• Preserves all your other Claude Code config (theme, sessions, project state, other MCP servers)
• Is idempotent: running it again updates the config without breaking anything

For staging environment:

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

For project scope (writes to <cwd>/.mcp.json instead, only affects the current project — useful for sharing via git):

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

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	Configure for production, user scope (~/.claude.json)
platform-mcp-setup --env staging	Configure for staging
platform-mcp-setup --scope project	Configure project scope (<cwd>/.mcp.json)
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

In Cursor, go to Settings > MCP and add a new server, or create a .cursor/mcp.json file 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"
      }
    }
  }
}

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