# Getting Started — SquareMCP Docs

# Getting started

Connect your AI assistant to SquareMCP in five minutes. Choose your client below.

## Step 1 — Create your account

1. Sign up at squaremcp.com Open the SquareMCP dashboard, create an account, and verify your email.
2. Get your access token Click Connect MCP Client in the dashboard. This opens a short OAuth flow that issues a Bearer token bound to your account. Copy the token shown on the confirmation page — it won't be displayed again.
3. Connect at least one platform Go to Platforms and connect LinkedIn, TikTok, WhatsApp, or any other service. See Platform guides for step-by-step instructions per platform.

## Step 2 — Configure your MCP client

Connect SquareMCP directly inside the claude.ai web interface — no config files needed.

1. Open MCP Servers — go to claude.ai → Settings → MCP Servers and click Add.
2. Enter the server URL

    https://hermes.squaremcp.com

3. Complete the OAuth flow — a popup will open at `hermes.squaremcp.com/login`. Sign in with your SquareMCP account credentials. After signing in you will be shown a consent page — click Connect MCP client. The popup closes and the connector shows as Connected.

Why a separate login page? Browsers partition cookies per top-level site. The OAuth popup runs on `hermes.squaremcp.com`, so your session must be established there — not on `app.squaremcp.com` — for the cookie to be visible.

### Troubleshooting claude.ai connections

Popup doesn't open — make sure your browser isn't blocking pop-ups from claude.ai. Allow pop-ups for claude.ai and retry.

Stuck on login after connecting — the popup may have been closed before the OAuth flow finished. Remove the server entry, click Add again, and complete the full popup flow.

Shows connected but tools don't appear — start a new conversation. Tools from newly connected MCP servers appear in the next conversation's tool picker.

    // ~/Library/Application Support/Claude/claude_desktop_config.json  (macOS)
    // %APPDATA%\Claude\claude_desktop_config.json                       (Windows)
    {
      "mcpServers": {
        "squaremcp": {
          "type": "http",
          "url": "https://hermes.squaremcp.com/mcp",
          "headers": {
            "Authorization": "Bearer YOUR_TOKEN_HERE"
          }
        }
      }
    }

Restart Claude Desktop after saving. You should see SquareMCP tools in the tool picker (hammer icon).

    # ~/.codex/config.json
    {
      "mcpServers": {
        "squaremcp": {
          "type": "http",
          "url": "https://hermes.squaremcp.com/mcp",
          "headers": {
            "Authorization": "Bearer YOUR_TOKEN_HERE"
          }
        }
      }
    }

Or pass inline per command:

    codex --mcp-server squaremcp=https://hermes.squaremcp.com/mcp \
          --mcp-header squaremcp:Authorization="Bearer YOUR_TOKEN_HERE" \
          "Post a LinkedIn update about today's product launch"

PKCE flow (optional) Codex CLI supports the full OAuth PKCE flow. Run `codex auth squaremcp` and follow the browser prompt — no token copy-paste required.

    # ~/.config/opencode/config.json
    {
      "mcp": {
        "servers": {
          "squaremcp": {
            "type": "http",
            "url": "https://hermes.squaremcp.com/mcp",
            "headers": {
              "Authorization": "Bearer YOUR_TOKEN_HERE"
            }
          }
        }
      }
    }

Save the file and restart opencode. The SquareMCP tools will appear in the tool list automatically.

## Step 3 — Verify the connection

Ask your AI assistant:

    What social platforms do I have connected?

It should call `get_profile` or `linkedin_get_profile` and return your account details. If you see a "Platform not connected" error, revisit the Platform guides.

## Available tools

SquareMCP exposes tools across every connected platform. A few highlights:

#### linkedin_create_post

Publish text, image, or video to your LinkedIn feed.

#### tiktok_create_video

Upload a video file and publish it to TikTok.

#### whatsapp_send_message

Send a WhatsApp message to any number via Business API.

#### twitter_create_tweet

Post a tweet with optional media attachment.

#### instagram_create_reel

Publish a reel to your Instagram Business account.

#### send_email

Send email from any connected IMAP/SMTP account.

See the full list in the API reference.

## Troubleshooting

### Tools not appearing in Claude

Restart Claude Desktop after editing `claude_desktop_config.json`. If tools still don't appear, open the Claude Desktop developer console and look for MCP connection errors.

### "Platform not connected" errors

The tool was called but the platform isn't linked to your account. Open the dashboard and connect the platform under Platforms.

### "Token expired" badge in dashboard

OAuth tokens for LinkedIn, TikTok, and Instagram expire. SquareMCP attempts an automatic refresh — if that fails, reconnect the platform. WhatsApp, Telegram, and Discord use long-lived bot tokens that don't expire.

### Rate limit errors

Each SquareMCP plan has a monthly tool-call limit. Check Usage in the dashboard. Upgrade your plan if you're consistently hitting the limit.

Keep your Bearer token secret Your Bearer token has full access to every connected platform. Treat it like a password. Rotate it from the dashboard if you suspect it's been exposed.