Connect with MCP

Connect Codex, OpenClaw, Hermes, Claude, and other MCP clients to AlonChat

Connect with MCP#

AlonChat exposes one hosted Model Context Protocol endpoint:

text
https://alonchat.com/api/mcp

Use it in two ways:

  • Account OAuth is the recommended choice for Codex, OpenClaw, Hermes, and other interactive clients. AlonChat opens a browser consent screen. You choose one project, all or selected agents, and the exact permissions to grant.
  • Project API keys are for servers, CI, customer-chat integrations, and other unattended automation. Keys can be restricted to selected agents and capabilities.

Both paths discover tools from the same versioned AlonChat operation catalog used by the public API, SDK, and CLI. MCP is a connector over AlonChat—it is not a second agent runtime and does not copy your knowledge base.

Connect with Account OAuth#

Codex#

bash
codex mcp add alonchat --url https://alonchat.com/api/mcp
codex mcp login alonchat

Complete the AlonChat consent screen in your browser, then use /mcp in Codex to verify the connection.

Claude Code#

bash
claude mcp add --transport http alonchat https://alonchat.com/api/mcp

Open Claude Code, run /mcp, and complete the OAuth sign-in for AlonChat.

OpenClaw#

bash
openclaw mcp set alonchat \
  '{"url":"https://alonchat.com/api/mcp","transport":"streamable-http","auth":"oauth"}'
openclaw mcp login alonchat
openclaw mcp doctor alonchat --probe

The AlonChat tools then become available to eligible OpenClaw runtimes. OpenClaw tool filters can further reduce which granted tools an agent sees.

Hermes#

Add this entry under mcp_servers in ~/.hermes/config.yaml:

yaml
mcp_servers:
  alonchat:
    url: 'https://alonchat.com/api/mcp'
    auth: oauth

Then authorize and verify:

bash
hermes mcp login alonchat
hermes mcp configure alonchat

Hermes supports browser, paste-back, and remote-host OAuth completion flows.

Other OAuth-capable MCP clients#

Add https://alonchat.com/api/mcp as a Streamable HTTP server. The client discovers AlonChat's protected-resource and authorization-server metadata, registers itself when needed, and starts an OAuth 2.1 authorization-code flow with PKCE.

The consent screen never asks you to paste an access token.

What OAuth Can Access#

One OAuth connection belongs to:

  • the signed-in AlonChat user;
  • one project;
  • all agents or an explicit agent allow-list;
  • an explicit set of AlonChat permissions.

Available permissions depend on the user's current project role and page permissions:

PermissionWhat it allows
agents.readList safe agent summaries
agent_design.readInspect setup, validate proposals, and read saved design sessions
conversations.readRead bounded production transcripts as agent-improvement evidence
agent_design.writeSave review-gated design drafts; it does not publish them
billing.readRead plan, usage, invoice summaries, and owner-controlled billing URLs

AlonChat rechecks the current membership, page permissions, agent scope, OAuth grant, and plan entitlement on every connection. Removing a member, reducing their permission, changing agent scope, or revoking the connection takes effect without waiting for a refresh token to expire.

Manage account-linked clients under Project Settings → MCP Connections.

OAuth MCP does not expose:

  • private AlonChat staff or platform administration;
  • projects the user cannot access;
  • plans not eligible for the selected project;
  • white-label administration;
  • publishing a design draft to a live agent;
  • payment, plan-change, or cancellation actions;
  • raw database access or generic CRUD.

Connected Services Stay Separate#

Authorizing an MCP client does not sign that client into Google Calendar, Gmail, Meta, Telegram, or another third-party service. Connect those services to the appropriate AlonChat agent in the web dashboard first.

An MCP operation may use an already-connected service only when that specific operation exists in AlonChat's catalog and the connection, user permission, agent scope, plan, and approval policy all allow it. The MCP client never receives the third-party access or refresh token. The initial OAuth catalog focuses on reviewing and drafting agent configuration; it does not provide arbitrary control of connected services.

Agent Improvement and Workflows#

An authorized coding or operations agent can inspect setup, read only the conversations needed as evidence, validate a complete proposal, and save a review-gated agent-design draft. The owner still reviews and applies it inside AlonChat.

MCP does not make every dashboard button callable. New procedure, workflow, source, and action capabilities appear only after AlonChat adds them to the canonical operation catalog with the required authorization, idempotency, approval, audit, and verified-readback controls. Compatible MCP clients discover those additions automatically.

Use a Project API Key#

Use a project key when a process cannot open a browser, when a backend should own the connection, or when you need the customer-chat tool.

For hosted Streamable HTTP, set the key as a Bearer token:

toml
[mcp_servers.alonchat_automation]
url = "https://alonchat.com/api/mcp"
bearer_token_env_var = "ALONCHAT_API_KEY"

The key controls the visible agents and tools. chat_with_agent runs the hosted AlonChat agent and uses that project's credits.

Run the npm STDIO Server#

For clients that start local processes:

toml
[mcp_servers.alonchat_local]
command = "npx"
args = ["-y", "@alonchat/mcp-server"]
env_vars = ["ALONCHAT_API_KEY"]

Set ALONCHAT_API_KEY in the environment that launches the client. The npm package contains the protocol adapter only; it calls AlonChat's hosted API and contains no AlonChat backend or service credentials.

Token and Subscription Costs#

  • The MCP client's model usage is charged by the provider running that client.
  • Reading AlonChat setup, conversations, design sessions, subscription, or usage data does not run an AlonChat model.
  • chat_with_agent runs the AlonChat customer agent and uses AlonChat project credits.
  • Saving a design draft through the workbench does not publish it or run the live customer agent.

Revoke a Connection#

Open Project Settings → MCP Connections and select Revoke. AlonChat immediately marks its business grant inactive and also revokes the upstream OAuth grant and refresh tokens. Already-issued access tokens are still blocked because every MCP call checks the AlonChat grant record.

For an API-key connection, revoke the key under Project Settings → API Keys.

Troubleshooting#

  • Browser login does not open: run the client's explicit MCP login command.
  • No eligible project: your current project role must allow at least one MCP operation.
  • Tool not listed: the consented permission, current role, agent scope, or project plan does not allow it.
  • Connection stopped after a role change: reconnect only after the project owner restores the required permission.
  • Chat tool missing on OAuth: intentional; use a narrowly scoped project API key for customer chat or unattended automation.
  • Retrying a draft after a timeout: reuse the same _alonchatIdempotencyKey.

Related Pages#