> ## Documentation Index
> Fetch the complete documentation index at: https://docs.a-char.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Setup

> Connect Claude Code, Claude, Cursor, Codex, Grok Bot, VS Code or any MCP client to the hosted A-Char MCP server by signing in or with an API key.

Connect Claude Code, Claude, Cursor, Codex, Grok Bot, VS Code or any MCP client to `https://a-char.com/api/mcp` by
signing in with your A-Char account or with an API key. The server is hosted, so there is nothing to
install; the [MCP page](/mcp) has a first tool call over plain HTTP.

## Authentication

The server accepts two credentials:

* **Sign in (OAuth)**: your MCP client opens a browser and you sign in with your A-Char account. There is
  no key to copy. This is the default.
* **API key**: create one under **Account Settings → API Keys** in A-Char (click your name at the bottom
  of the sidebar) and pass it in the `Authorization: Bearer` header. Pick only the scopes the assistant
  needs; the server lists only the tools they allow. Use this to choose the scopes yourself, for clients
  without OAuth support, and for autonomous agents.

A client that supports OAuth needs only the server URL: the server advertises its authorization flow and the
client walks you through sign-in on first use. The server implements the MCP authorization spec, OAuth 2.1
with PKCE and discovery metadata.

Either way the assistant acts as you, in one organization, and can never do more than your role allows.

<Warning>
  Config files are not shell scripts. Wherever a sample on this page shows `$A_CHAR_API_KEY`,
  paste the key itself if your client does not expand environment variables, or the header arrives empty
  and you get a `401`.
</Warning>

## Connect your client

<Tabs>
  <Tab title="Claude Code">
    If you have connected A-Char in [Claude](/claude-connector), Claude Code already has it when you are
    signed in with the same Claude account. Run `/mcp` and it is listed as **claude.ai A-Char**; there is
    nothing to add.

    Otherwise, add the server:

    ```bash theme={null}
    claude mcp add --transport http a-char https://a-char.com/api/mcp
    ```

    Then sign in with your A-Char account: run `/mcp`, pick **a-char** and choose **Authenticate**.

    ```bash theme={null}
    claude /mcp
    ```

    Add `--scope user` to the first command to use A-Char in every project, not just this one.

    To use an API key instead of signing in, pass it when adding the server:

    ```bash theme={null}
    claude mcp add --transport http a-char https://a-char.com/api/mcp \
      --header "Authorization: Bearer $A_CHAR_API_KEY"
    ```

    The Claude Code [documentation](https://docs.claude.com/en/docs/claude-code/mcp) covers MCP servers in
    general.
  </Tab>

  <Tab title="Claude">
    A-Char is an official connector in Claude's directory. In Claude (web, desktop or mobile), open
    **Settings → Connectors → Browse connectors**, find **A-Char** and click **Connect**. Claude redirects
    you to sign in with your A-Char account, then the connector activates; no API key is needed.

    The connector also appears in Claude Code under the same Claude account. The
    [Claude connector](/claude-connector) guide covers Team and Enterprise setup, tool permissions and
    example prompts.
  </Tab>

  <Tab title="Cursor">
    Put this in `~/.cursor/mcp.json` (or a project's `.cursor/mcp.json`):

    ```json theme={null}
    {
      "mcpServers": {
        "a-char": {
          "url": "https://a-char.com/api/mcp"
        }
      }
    }
    ```

    Cursor prompts you to sign in with your A-Char account. To use an API key instead, pass it as a header:

    ```json theme={null}
    {
      "mcpServers": {
        "a-char": {
          "url": "https://a-char.com/api/mcp",
          "headers": {
            "Authorization": "Bearer $A_CHAR_API_KEY"
          }
        }
      }
    }
    ```

    The Cursor [documentation](https://docs.cursor.com/context/model-context-protocol) covers the file
    format.
  </Tab>

  <Tab title="Codex">
    Add the server:

    ```bash theme={null}
    codex mcp add a-char --url https://a-char.com/api/mcp
    ```

    Then sign in with your A-Char account:

    ```bash theme={null}
    codex mcp login a-char
    ```

    This writes the following to `~/.codex/config.toml`:

    ```toml theme={null}
    [mcp_servers.a-char]
    url = "https://a-char.com/api/mcp"
    ```

    To use an API key instead, reference it from an environment variable:

    ```toml theme={null}
    [mcp_servers.a-char]
    url = "https://a-char.com/api/mcp"
    bearer_token_env_var = "A_CHAR_API_KEY"
    ```

    The Codex [documentation](https://developers.openai.com/codex/mcp) covers the file format.
  </Tab>

  <Tab title="Grok Bot">
    Open **Settings → Plugins → Add a custom connector** and enter the server URL:

    * **Server URL:** `https://a-char.com/api/mcp`

    Save it, and Grok Bot redirects you to sign in with your A-Char account. Then attach A-Char to a task by
    typing **@A-Char** in the message box.

    To use an API key instead of signing in, add it as the connector's auth header:

    * **Auth:** `Authorization: Bearer $A_CHAR_API_KEY`

    The xAI [documentation](https://docs.x.ai/grok/connectors) covers connectors in Grok.
  </Tab>

  <Tab title="VS Code">
    Put this in the project's `.vscode/mcp.json`:

    ```json theme={null}
    {
      "servers": {
        "a-char": {
          "type": "http",
          "url": "https://a-char.com/api/mcp"
        }
      }
    }
    ```

    VS Code prompts you to sign in with your A-Char account. To use an API key instead, have VS Code ask for
    it once and store it securely, so it never lands in the file:

    ```json theme={null}
    {
      "inputs": [
        { "type": "promptString", "id": "a-char-key", "description": "A-Char API key", "password": true }
      ],
      "servers": {
        "a-char": {
          "type": "http",
          "url": "https://a-char.com/api/mcp",
          "headers": {
            "Authorization": "Bearer ${input:a-char-key}"
          }
        }
      }
    }
    ```

    The VS Code [documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) covers the file
    format.
  </Tab>

  <Tab title="Other">
    Use the server URL `https://a-char.com/api/mcp` and sign in when your client supports OAuth.

    If your client does not support OAuth, pass an API key in the `Authorization` header. A client might
    accept this shape:

    ```json theme={null}
    {
      "a-char": {
        "url": "https://a-char.com/api/mcp",
        "headers": {
          "Authorization": "Bearer $A_CHAR_API_KEY"
        }
      }
    }
    ```

    #### stdio-only clients

    If your client only supports local stdio servers (`command` plus `args`, such as Claude Desktop's
    `claude_desktop_config.json`), bridge to the hosted server with
    [`mcp-remote`](https://www.npmjs.com/package/mcp-remote):

    ```json theme={null}
    {
      "mcpServers": {
        "a-char": {
          "command": "npx",
          "args": [
            "-y",
            "mcp-remote@latest",
            "https://a-char.com/api/mcp",
            "--header",
            "Authorization: Bearer $A_CHAR_API_KEY"
          ]
        }
      }
    }
    ```

    Omit the two `--header` entries to sign in instead; `mcp-remote` opens a browser window for it.
  </Tab>
</Tabs>

Confirm the connection the same way in any client: ask the assistant how many vacation days you have left. A
working server answers from the `get_time_off_balances` tool with one line per policy, or says you have no
policies when HR has not assigned you any yet. Anything else is one of the failures below.

## Building autonomous agents

An agent passes an API key as the bearer credential straight to the hosted server; it speaks Streamable HTTP,
so any MCP SDK or plain HTTP works. The [MCP page](/mcp#autonomous-agents) has a complete `tools/call`
request with its response.

Do not embed API keys in code. Provide them to the agent through a secrets vault or an environment variable,
and create a dedicated key per agent with only the scopes it needs, so you can revoke it independently.

## If it fails

### `401 Unauthorized`

The server rejected the credential. When signed in, remove and re-add the server so the client runs sign-in
again. With an API key, check it in **Account Settings → API Keys**: it must not be revoked or expired, and
must be copied without extra spaces.

### Sign-in finishes, but the connection fails

Your A-Char account belongs to more than one organization, and sign-in cannot yet choose between them. Use an
API key, which is created inside one organization.

### Claude connector says `Couldn't reach the MCP server`

Disconnect A-Char in Claude's **Settings → Connectors** and connect it again. Claude caches a failed authorization attempt, so a stale failure
persists until you reconnect.

### A tool is missing

An API key lists only the tools its scopes allow: `time-off:read` for reading, `time-off:write` for booking,
changing and cancelling, `time-off:review` for approving and declining. Approving and declining also need you
to be an approver. Reconnect after changing a key's scopes, since clients cache the tool list.

### `406 Not Acceptable`

Plain HTTP requests must send `Accept: application/json, text/event-stream`. MCP SDKs do this for you.

### Changes not taking effect

After editing your client's MCP configuration, restart the client completely.

## Related

* [MCP](/mcp): a first tool call over plain HTTP and how the server behaves.
* [Tools](/mcp/tools): every tool's parameters and the `tools/list` catalog.
* [Claude connector](/claude-connector): step-by-step setup in Claude.
* [Authentication](/authentication): API keys, scopes and roles.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.