Kallfi ACR Documentation

Give your AI client access to Kallfi with your Account's ACR key.

Run setup

npx @kallfi/mcp@latest setup

Choose your client and configuration scope, then review and confirm the changes. Remote HTTP is the default; Local stdio is optional.

Node.js for local setup

The installer and Local stdio require Node.js 22 or later. A direct Remote HTTP connection does not require a local Kallfi server or Node.js.

Add your credentials

Open your ACR account to reveal the key for this surface. Basic Account access does not require Enterprise approval.

In user scope, setup can save the key in your client's private configuration. Values are masked during entry and saved as plaintext in private user files and backups with mode 0600. Keep both private. Setup refuses private key storage inside a project or Git checkout; project scope uses environment references.

For environment-reference configuration, make KALLFI_RED_ACR_KEY available to the process that launches your client. Supply the raw key without a Bearer prefix. A desktop app may need its own environment configuration and a restart.

Run setup again after key rotation and choose Replace. Setup preserves unrelated settings, asks before changes, and leaves the original file unchanged if you cancel before confirmation. It does not create, rotate or validate keys through a server call.

Configure your client

Choose Claude Code, Codex, Cursor or Manus. The first three support Remote HTTP and Local stdio recipes; Manus uses guided cloud setup.

User configuration: ~/.claude.json. Project configuration: <project>/.mcp.json.

{
  "mcpServers": {
    "kallfi-red": {
      "type": "http",
      "url": "https://mcp.kallfi.red/mcp",
      "headers": {
        "Authorization": "Bearer ${KALLFI_RED_ACR_KEY}"
      }
    }
  }
}

For Remote HTTP, use https://mcp.kallfi.red/mcp with a client that supports Streamable HTTP and a Bearer API key or custom Authorization header.

API key authentication

Kallfi MCP uses an Account API key, not OAuth. OAuth-only connectors are unsupported. Keep the key out of URLs, chat messages, tool arguments and shared configuration.

Restart your client after changing its configuration. To remove an installer-managed connection, run npx @kallfi/mcp@latest remove and select that connection.

Check your connection

List the tools, then try a permitted read. See Tools and capabilities for available actions. Tool discovery does not grant permissions or establish that every business operation succeeds.

Personal and Team access

Omit workspace selection for Personal and Account tools. Explicit Team workspace execution is currently unsupported and returns workspace_capability_unsupported; do not retry it as Personal.

Paid actions and mutations still require their normal permissions and confirmations. Retain the original idempotency key when retrying an action; a timeout or cancellation does not roll it back.

Troubleshooting

Problem	What to check
Local process does not start	Check Node.js 22+, the client's executable path and valid configuration.
Authentication is rejected	Check the key is current, unrevoked and issued for this surface.
Configuration changes have no effect	Save the private configuration and restart the client.
The connector offers only OAuth	Use a client with API-key Bearer support.
Remote transport is rejected	Use stateless POST Streamable HTTP; GET streams, resumable sessions and subscriptions are unsupported.

Product entry and exact tool catalog

The product MCP entry uses the same maintained setup command as the developer entry. Its terminal-style row provides a copy control and screen-reader status; failed clipboard access offers manual selection instead of claiming success. Client marks identify Claude Code, Codex, Cursor and guided Manus setup; they do not certify every client transport or grant access.

The proposed presentation rounds its marketing count down to a multiple of ten (for example, thirty-eight published tools appears as “30+”). The exact list/count remains the published versioned catalog in Tools and the API reference. Marketing copy and metadata are not a capability-admission signal.

Following workspace implementation

The following ACR overhaul preserves this published package setup and the verified hosted Personal reads. Its optional X-Kallfi-Workspace-ID selector identifies an intended workspace only; the shared SDK requires same-origin protocol support before sending an explicitly scoped business request, then canonical owners require current membership, surface and grants. The shared SDK rejects an explicit configured workspace for Account-scoped tools, including a Personal UUID; keep those tools on the unscoped Personal connection. Current hosted Team requests remain workspace_capability_unsupported without fallback until the matching schema and runtime are installed. Restricted Personal browser metadata does not grant API-key, Team or tool execution. No new OAuth support is implied.

Setup