Setup - A-Char API

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 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.

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.

Connect your client

If you have connected A-Char in Claude, 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:

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.

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:

claude mcp add --transport http a-char https://a-char.com/api/mcp \
  --header "Authorization: Bearer $A_CHAR_API_KEY"

The Claude Code documentation covers MCP servers in general.

Put this in ~/.cursor/mcp.json (or a project’s .cursor/mcp.json):

{
  "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:

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

The Cursor documentation covers the file format.

Add the server:

codex mcp add a-char --url https://a-char.com/api/mcp

Then sign in with your A-Char account:

codex mcp login a-char

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

[mcp_servers.a-char]
url = "https://a-char.com/api/mcp"

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

[mcp_servers.a-char]
url = "https://a-char.com/api/mcp"
bearer_token_env_var = "A_CHAR_API_KEY"

The Codex documentation covers the file format.

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 covers connectors in Grok.

Put this in the project’s .vscode/mcp.json:

{
  "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:

{
  "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 covers the file format.

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:

{
  "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:

{
  "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.

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 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. 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.

MCP: a first tool call over plain HTTP and how the server behaves.
Tools: every tool’s parameters and the tools/list catalog.
Claude connector: step-by-step setup in Claude.
Authentication: API keys, scopes and roles.

​Authentication

​Connect your client

​stdio-only clients

​Building autonomous agents

​If it fails

​401 Unauthorized

​Sign-in finishes, but the connection fails

​Claude connector says Couldn't reach the MCP server

​A tool is missing

​406 Not Acceptable

​Changes not taking effect

​Related

Authentication

Connect your client

stdio-only clients

Building autonomous agents

If it fails

`401 Unauthorized`

Sign-in finishes, but the connection fails

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

A tool is missing

`406 Not Acceptable`

Changes not taking effect

Related