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:

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. A tool listed in an installed package is not permission to call it. Discovery returns only what this connection, project, and agent scope allow.

The AlonChat CLI can generate or run the reviewed setup for common clients:

alonchat mcp install --client codex --execute
alonchat mcp install --client claude --execute
alonchat mcp install --client cursor

Cursor and generic-client setup prints configuration for review instead of silently changing the other application's files.

Connect with Account OAuth#

Codex#

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#

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#

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:

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

Then authorize and verify:

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.

The consent screen offers three understandable starting points: Read-only setup, Build agents, and Full delegated access. You can then customize individual permissions. Presets never bypass the user's current role, selected-agent scope, plan, operation risk, or approval rules.

The consent screen lists every scope the current role can grant. Presets are only starting points. These are the scopes the rest of this page refers to:

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 capture, plan-change, or cancellation actions;
• raw database access or generic CRUD.

With handover.write, a client can use send_customer_reply, control_ai_reply, resume_ai_reply, and resolve_handover for the selected agents. A pause must include an explicit duration, including forever. A customer reply is a live consequential action: the first call creates a durable approval for the exact message, the owner approves it in AlonChat, and the client retries with the same idempotency key. A successful retry returns a task receipt; use get_task before claiming provider delivery.

With callback_requests.write, manage_callback_request can update or schedule one existing customer callback request. It cannot invent permission to contact: recording permission requires an owner note, and the exact change requires approval before AlonChat applies and reads back its durable Activity state.

With bookings.write, create_booking creates one booking attached to an exact existing conversation. The request must include the confirmed slot and reviewable customer-confirmation evidence. AlonChat then requires owner approval, rechecks commerce prerequisites and live slot capacity, creates the internal booking idempotently, and reports connected-calendar projection separately so a projection problem is never mistaken for a missing internal booking.

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 OAuth catalog exposes only named, durable operations; 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. Hosted MCP clients discover eligible additions after AlonChat deploys them and the client reconnects. The local npm STDIO server can expose only operation contracts included in its installed package version, so upgrade @alonchat/mcp-server and restart the client when AlonChat publishes a new operation.

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:

[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#

STDIO means standard input/output. In this mode, the MCP client starts a local AlonChat adapter and communicates with it through process pipes. Use it for local development, self-hosted runners, or clients that cannot use hosted OAuth; it is not a second AlonChat backend.

The local adapter reuses the same named credential profiles as the CLI:

alonchat auth login --profile work
npx -y @alonchat/mcp-server --profile work

For clients that start local processes with the saved default profile:

[mcp_servers.alonchat_local_dev]
command = "npx"
args = ["-y", "@alonchat/mcp-server"]

The _local_dev name is intentional: this is a local API-key process, not the hosted OAuth connection. Use alonchat for https://alonchat.com/api/mcp so status and login commands cannot silently target the wrong transport.

For unattended execution, set ALONCHAT_API_KEY in the environment that launches the client and add env_vars = ["ALONCHAT_API_KEY"] to the client configuration. The npm package contains the protocol adapter only; it calls AlonChat's hosted API and contains no AlonChat backend or service credentials. Existing operation behavior and live project data remain server-side and do not require a package update. Completely new operation contracts require a newer package version.

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.
• get_subscription, get_usage, list_plans, and list_invoices all require billing.read (billing_read on a project API key). They cannot charge a card, change a plan, or cancel a subscription.

Operation results#

A tool can finish, return background work, or wait for approval. Treat the receipt as the result, not the model's summary of it.

Tool failures set isError: true. When the API returned a receipt, that receipt is preserved. Otherwise the error includes code, message, HTTP status, and retryable. An OUTCOME_UNCERTAIN result is not permission to repeat the action with a new idempotency key. Reconcile the earlier outcome first.

A document upload can stay pending_approval before any bytes are stored. A completed file or spreadsheet transfer is still separate from source training or structured import. Read the source status before telling someone the knowledge is live.

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.
• CLI or local STDIO has no credential: run alonchat auth login, select a saved profile with --profile, or set ALONCHAT_API_KEY for unattended execution.
• Unsure which local credential is active: run alonchat whoami and alonchat doctor.
• 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. chat_with_agent simulates a customer talking to the hosted agent and remains API-key-only. For a reviewed human reply to an existing live conversation, grant handover.write and use send_customer_reply.
• Customer reply is pending: approve the exact operation in AlonChat, then retry with the same _alonchatIdempotencyKey and follow the returned task receipt.
• Retrying a draft after a timeout: reuse the same _alonchatIdempotencyKey.

Related Pages#

• Connect to an Agent
• Build agents with Codex or Claude
• SDK and CLI
• Authentication
• Chat API
• Connectors, subscriptions, and token costs