Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.archal.ai/llms.txt

Use this file to discover all available pages before exploring further.

Every Archal twin speaks MCP over HTTP at a stable URL for the lifetime of a session. Any compliant MCP client can connect — Claude Desktop, Cline, your own MCP host, anything that can hit an HTTP MCP endpoint with a bearer token. This is the right workflow when you want to drive a twin interactively from a tool that isn’t archal run — for example manually debugging prompt behavior inside Claude Desktop against a hosted GitHub twin.

​
1. Start a persistent session

archal twin start github
Copy the MCP URL from the output. It looks like: 
github
  MCP      https://ses-01hxyz.twins.archal.ai/github/mcp
  Base URL https://ses-01hxyz.twins.archal.ai/github/api
The session stays alive for 30 minutes of inactivity — extend with archal twin renew 7200 if you need longer.

​
2. Grab an auth token

MCP calls against a hosted twin require a bearer token. Use your ARCHAL_TOKEN (from archal login or the dashboard).
Treat ARCHAL_TOKEN as a credential. Don’t echo it in shared terminals, paste it into chat, or commit it to a config file checked into version control. Prefer your OS keychain or a secret-manager-backed env var. If your MCP client supports ${ENV_VAR} interpolation in its config, use that rather than pasting the raw token into JSON.
Two ways to get the token value, neither of which involves echoing it to a shared terminal:
  • Export it once in your shell profile: export ARCHAL_TOKEN=arc_... (from the dashboard) and reference it below as ${ARCHAL_TOKEN}.
  • Or, if you logged in with archal login, read it directly into the client config at launch: $(jq -r .token ~/.archal/credentials.json) as a command substitution — the value flows into the client without touching your terminal history.

​
3. Add the twin to your MCP client’s config

Point the client at the MCP URL, with Authorization: Bearer <token> as a header. Shape varies per client; two common examples:

​
Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json: 
{
  "mcpServers": {
    "archal-github": {
      "url": "https://ses-01hxyz.twins.archal.ai/github/mcp",
      "headers": {
        "Authorization": "Bearer ${ARCHAL_TOKEN}"
      }
    }
  }
}
Use ${ENV_VAR} interpolation so the raw token never ends up in the config file on disk. If the client doesn’t support interpolation, store the token in your OS keychain and retrieve it at launch time; avoid pasting a literal arc_... string into this JSON. Restart the app. The twin’s tools show up alongside your other MCP servers.

​
Cline / Cursor / any config-file-based MCP host

Use the same two fields — an HTTP URL for the twin and a Bearer header with your ARCHAL_TOKEN. Some clients expect the header as auth or authorization; check the client’s docs.

​
4. Use it

Issue prompts as you normally would. Every tool call the model makes is handled by the twin’s in-memory state engine, not the real service. State persists across calls for the life of the session — create an issue, list issues, and the new one shows up.

​
Teardown

archal twin stop
That releases the hosted session and invalidates the URL. Any clients still pointed at it will get 404s until you start a new session.

​
Caveats

  • Only MCP-capable twins support this flow. All current twins expose MCP, so in practice every entry in the twins overview works.
  • The MCP URL is session-scoped. Restart the session and the host portion of the URL changes; update your client config or use archal twin attach to re-attach to an existing session from a different shell.
  • This flow skips Archal’s scenario runner and evaluator entirely — there is no satisfaction score. Use it for exploration, not grading.