Skip to main content

Connecting clients

This page shows how to register the Smily MCP server with the most common MCP clients. In every case you need:

Throughout, replace mcp_YOUR_TOKEN with your actual token.

Header vs. URL auth

Clients that can send custom headers should use Authorization: Bearer mcp_YOUR_TOKEN. Clients that can only be given a URL (notably Claude Cowork) use the ?token=mcp_YOUR_TOKEN query parameter instead. Both are explained in Authentication.

Multi-account tokens

If your token can reach multiple accounts, pin the active one per request — add account_id to the tool arguments, or set an X-BookingSync-Account-ID header (most clients let you add static headers alongside Authorization). Single-account tokens need none of this.

Claude Code​

Claude Code supports remote HTTP MCP servers natively. Add the server with one command:

claude mcp add --transport http smily https://www.bookingsync.com/mcp \
  --header "Authorization: Bearer mcp_YOUR_TOKEN"
Argument order matters

The server name (smily) and URL must come before the --header flag.

To keep the token out of your shell history, reference an environment variable instead:

export SMILY_MCP_TOKEN="mcp_YOUR_TOKEN"
claude mcp add --transport http smily https://www.bookingsync.com/mcp \
  --header "Authorization: Bearer $SMILY_MCP_TOKEN"

Project-scoped configuration (.mcp.json)​

To share the server with a project (committed to source control, token kept out of it), add an .mcp.json at the project root:

{
  "mcpServers": {
    "smily": {
      "type": "http",
      "url": "https://www.bookingsync.com/mcp",
      "headers": {
        "Authorization": "Bearer mcp_YOUR_TOKEN"
      }
    }
  }
}

Verify the connection with claude mcp list, then in a session run /mcp to see the available tools (api_v3_resources, api_v3_resource_schema, api_v3_list, api_v3_get).

Claude Cowork​

Claude Cowork (and the connector experience on claude.ai, Claude Desktop, and the mobile apps) adds remote MCP servers as custom connectors by URL. These clients connect to your server from Anthropic's cloud, and at the time of writing Claude Cowork does not let you specify request headers — so you can't send Authorization: Bearer. The only option there is to put the token in the URL:

Not the recommended approach

Putting the token in the URL is less secure than a header (see Authentication → prefer headers) and is not recommended in general. Use it only with clients like Claude Cowork that can't send headers. Where your client supports headers (Claude Code, Codex, MCP Inspector), use Authorization: Bearer instead.

  1. Open Customize → Connectors (or the + next to Connectors).
  2. Click Add custom connector.
  3. Name: Smily
  4. URL: 
    https://www.bookingsync.com/mcp?token=mcp_YOUR_TOKEN
  5. Save. Leave the OAuth Client ID / Secret fields empty — the Smily MCP server authenticates via the token in the URL, not OAuth.
  6. In a conversation, enable the connector from the + → Connectors menu.
The URL contains a secret

Because the token is embedded in the URL, treat the whole connector URL as a credential. Smily redacts the token parameter from its own logs and error tracking, but anyone who can see the connector configuration can read the token. Revoke and replace it if it leaks.

Network reachability

Custom connectors connect from Anthropic's infrastructure over the public internet — www.bookingsync.com is publicly reachable, so no firewall changes are needed.

OpenAI Codex​

Codex CLI stores MCP servers in ~/.codex/config.toml (or a project-scoped .codex/config.toml in trusted projects). It supports streamable HTTP servers directly.

[mcp_servers.smily]
url = "https://www.bookingsync.com/mcp"
bearer_token_env_var = "SMILY_MCP_TOKEN"

bearer_token_env_var names an environment variable whose value Codex sends as the Authorization: Bearer token, so the secret stays out of the config file:

export SMILY_MCP_TOKEN="mcp_YOUR_TOKEN"

If your Codex version supports arbitrary headers, you can instead use:

[mcp_servers.smily]
url = "https://www.bookingsync.com/mcp"
http_headers = { Authorization = "Bearer mcp_YOUR_TOKEN" }

Other clients (mcp-remote bridge)​

For an MCP client that only speaks stdio (e.g. older Claude Desktop configurations, or clients without native HTTP transport), bridge to the HTTP endpoint with the mcp-remote adapter:

{
  "mcpServers": {
    "smily": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://www.bookingsync.com/mcp",
        "--header", "Authorization: Bearer mcp_YOUR_TOKEN"
      ]
    }
  }
}

This works with any client that accepts a command/args stdio server definition.

Verifying with raw HTTP​

You don't need a client to test the server — curl works. See Protocol & transport for a full initialize → tools/list → tools/call walkthrough. The quickest smoke test is the unauthenticated health probe:

curl https://www.bookingsync.com/mcp/health
# => {"status":"ok","server":"bookingsync-mcp","version":"1.0.0","protocol_version":"2025-06-18"}

Troubleshooting​

SymptomLikely causeFix
Unauthorized (-32000)Missing, invalid, expired, or revoked token.Check the token; generate a new one if needed. See Authentication.
Session not found or expired (-32001)Client didn't echo Mcp-Session-Id, or the 1-hour session expired.Re-initialize. Most clients do this automatically. See Protocol → Sessions.
Rate limit exceeded (-32029, HTTP 429)More than 1,000 requests in an hour.Wait for Retry-After seconds. See Authentication → Rate limiting.
Connector can't reach the serverHeader-based auth on a header-less client.Use the ?token= URL form (Claude Cowork).
account_id is required for this token (-32602)Multi-account token without an account pinned.Pass account_id (or the X-BookingSync-Account-ID header). See account selection.
Invalid params (-32602)Unknown resource, attribute, operator, or field.Call api_v3_resources / api_v3_resource_schema to get valid values.