Connect an agent - asobeast

There are two transports and they expose the same tools.

Transport	What runs where	Use it when
Hosted endpoint	Your client connects to `POST /mcp` on your instance. Nothing to install	You want the shortest path, and your instance is reachable from the agent
Local stdio server	Your client launches `apps/mcp/dist/index.js` on your own machine, which calls the HTTP API	You are running from a checkout, or your client has no remote transport

The tool catalog is one set of definitions consumed by both, so there is no hosted only tool and no self hosted only tool. See MCP tool reference. Both transports serve MCP 2026-07-28 and the 2025 revisions, and none of the commands below carry a protocol version, so none of them change with the revision your client picks. See The asobeast MCP server. Either way the Settings card writes the configuration for you. The manual path is the same thing typed by hand.

Connect to the hosted endpoint

Mint a read only token

Open the MCP server card in Settings and click connect an agent. The token is read only, which is all any tool needs.

Copy the hosted snippet

The card shows the endpoint and a ready to paste command, pre filled with the origin you are browsing.

Run in a terminal.

claude mcp add --transport http asobeast https://your-host/api/backend/mcp --header "Authorization: Bearer asob_…"

Run in a macOS or Linux terminal. add-json takes one server entry, not a whole configuration file.

claude mcp add-json asobeast '{"type":"http","url":"https://your-host/api/backend/mcp","headers":{"Authorization":"Bearer asob_…"}}'

Put this in .mcp.json at the project root and commit it. It holds no secret: export ASOBEAST_API_TOKEN in your shell before you start claude, which expands the variable.

.mcp.json

{
  "mcpServers": {
    "asobeast": {
      "type": "http",
      "url": "https://your-host/api/backend/mcp",
      "headers": { "Authorization": "Bearer ${ASOBEAST_API_TOKEN}" }
    }
  }
}

Claude Desktop’s configuration file only runs local commands, and its Connectors screen has no field for a token. The entry below runs mcp-remote, a small local bridge that connects to the endpoint with your token. Open Settings, Developer, Edit Config, and merge the entry into the existing mcpServers object. It needs Node 18 or newer.

claude_desktop_config.json

{
  "mcpServers": {
    "asobeast": {
      "command": "npx",
      "args": [
        "-y",
        "[email protected]",
        "https://your-host/api/backend/mcp",
        "--header",
        "Authorization:${ASOBEAST_AUTH_HEADER}"
      ],
      "env": { "ASOBEAST_AUTH_HEADER": "Bearer asob_…" }
    }
  }
}

The header value lives in env because no argument may contain a space. For a plain http:// origin other than localhost or 127.0.0.1, add "--allow-http" directly after the endpoint.

Codex reads ~/.codex/config.toml, which the CLI, the IDE extension and the app share.

~/.codex/config.toml

[mcp_servers.asobeast]
url = "https://your-host/api/backend/mcp"
http_headers = { Authorization = "Bearer asob_…" }

The command form keeps the token out of the file and reads it from ASOBEAST_API_TOKEN whenever Codex starts. Export the variable in your shell profile. A Codex app launched from the dock does not see shell exports, so use the file above there.

codex mcp add asobeast --url https://your-host/api/backend/mcp --bearer-token-env-var ASOBEAST_API_TOKEN

Put this in ~/.cursor/mcp.json, or in .cursor/mcp.json inside a project.

~/.cursor/mcp.json

{
  "mcpServers": {
    "asobeast": {
      "url": "https://your-host/api/backend/mcp",
      "headers": { "Authorization": "Bearer asob_…" }
    }
  }
}

Put this in .vscode/mcp.json. The top level key is servers, not mcpServers, and "type": "http" is required. VS Code asks for the token the first time the server starts and keeps it in its secret storage, so the file holds no secret.

.vscode/mcp.json

{
  "inputs": [
    {
      "type": "promptString",
      "id": "asobeast-token",
      "description": "asobeast personal API token",
      "password": true
    }
  ],
  "servers": {
    "asobeast": {
      "type": "http",
      "url": "https://your-host/api/backend/mcp",
      "headers": { "Authorization": "Bearer ${input:asobeast-token}" }
    }
  }
}

Gemini CLI names streamable HTTP httpUrl. A url key selects the older SSE transport and never connects to asobeast.

~/.gemini/settings.json

{
  "mcpServers": {
    "asobeast": {
      "httpUrl": "https://your-host/api/backend/mcp",
      "headers": { "Authorization": "Bearer asob_…" }
    }
  }
}

Or add it with one command:

gemini mcp add --transport http --scope user --header "Authorization: Bearer asob_…" asobeast https://your-host/api/backend/mcp

Windsurf names the address serverUrl, and ignores a url key.

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "asobeast": {
      "serverUrl": "https://your-host/api/backend/mcp",
      "headers": { "Authorization": "Bearer asob_…" }
    }
  }
}

Point the client at the endpoint over streamable HTTP and send the token as a request header.

Setting	Value
Endpoint	`https://your-host/api/backend/mcp`
Transport	Streamable HTTP
Header	`Authorization: Bearer asob_…`

A client that only runs local commands can use the Claude Desktop entry, which bridges through mcp-remote.

The endpoint authenticates with the same asob_ token as the REST API, so there is no second credential to manage. Every request is authenticated, entitled and rate limited exactly like a REST call. See Rate limits and quotas. A token is the only credential it takes. A browser session cookie is answered with 401 even when it belongs to a signed in owner, so the endpoint carries no ambient authority a page could borrow.

The quick path for the stdio server

Open the MCP server card in Settings

Click connect an agent and name a token

asobeast mints the token and shows two ready to paste snippets, the Claude Code command and the Claude Desktop configuration, pre filled with the origin you are browsing.

Replace the entrypoint with an absolute path

The snippet cannot know where your checkout lives. Substitute the absolute path to apps/mcp/dist/index.js.

The token is shown once. Copy it before you leave the page.

The manual path

Build the server

pnpm build

This produces apps/mcp/dist/index.js.

Mint a personal API token

Use the API tokens card in Settings. See Personal API tokens.

Use the configuration below.

Client configuration for stdio

Claude Code
Claude Desktop
Codex
Cursor
Any stdio client

claude mcp add asobeast --env ASOBEAST_API_URL=http://localhost:4000 --env ASOBEAST_API_TOKEN=asob_… -- node "/absolute/path/to/asobeast/apps/mcp/dist/index.js"

claude_desktop_config.json

{
  "mcpServers": {
    "asobeast": {
      "command": "node",
      "args": ["/absolute/path/to/asobeast/apps/mcp/dist/index.js"],
      "env": {
        "ASOBEAST_API_URL": "http://localhost:4000",
        "ASOBEAST_API_TOKEN": "asob_…"
      }
    }
  }
}

~/.codex/config.toml

[mcp_servers.asobeast]
command = "node"
args = ["/absolute/path/to/asobeast/apps/mcp/dist/index.js"]
env = { ASOBEAST_API_URL = "http://localhost:4000", ASOBEAST_API_TOKEN = "asob_…" }

~/.cursor/mcp.json

{
  "mcpServers": {
    "asobeast": {
      "command": "node",
      "args": ["/absolute/path/to/asobeast/apps/mcp/dist/index.js"],
      "env": {
        "ASOBEAST_API_URL": "http://localhost:4000",
        "ASOBEAST_API_TOKEN": "asob_…"
      }
    }
  }
}

ASOBEAST_API_URL=http://localhost:4000 \
ASOBEAST_API_TOKEN=asob_… \
node "/absolute/path/to/asobeast/apps/mcp/dist/index.js"

Always use an absolute path to the entrypoint. Claude Desktop and Claude Code do not necessarily launch the process from your repository root, so a relative path fails with MODULE_NOT_FOUND. This is the most common setup failure.

Choosing ASOBEAST_API_URL

ASOBEAST_API_URL is resolved on the machine the agent runs on, not by a browser. That is the second most common failure, because the value that works in your address bar is often not the value the agent needs.

Where the agent runs	Value
The same host as the instance	`http://localhost:4000`
Anywhere else	Your public web origin plus `/api/backend`

The proxy path is not a fallback. In a Compose deployment the API is on a private network and is never published, so https://your-host/api/backend is the only route in from another machine. The proxy forwards the bearer header to the API unchanged. See How asobeast works. It defaults to http://localhost:4000, and an empty value counts as unset, so a template that leaves it blank still gets the default. There is no default for the token. The value is the REST API, so it never ends in /mcp. The hosted endpoint is a different transport, and the server refuses a URL copied from its snippet with the value to set instead. Plain http:// to a host other than this machine logs a warning at startup, because the token travels unencrypted. It still connects, since a private network you trust is a legitimate place to run it. Use https:// everywhere else.

Verify the connection

At startup the server checks its configuration and calls /auth/me on your instance before it registers a single tool. Each of these outcomes ends the process with a non zero exit status and a message that names the variable to change.

Situation	What you see
`ASOBEAST_API_TOKEN` unset or empty	A message telling you to set it to a personal API token
`ASOBEAST_API_TOKEN` does not start with `asob_`	A message that it must be a personal API token. A pasted `Bearer` prefix or surrounding quotes are removed for you
`ASOBEAST_API_URL` is not an absolute `http://` or `https://` address	A message showing the form it needs, such as `https://your-host/api/backend`
`ASOBEAST_API_URL` ends in `/mcp`	A message giving the same value without `/mcp`
`ASOBEAST_API_URL` has a query string, a fragment or a user name and password	A message giving the value without them. The token goes in `ASOBEAST_API_TOKEN`
`ASOBEAST_API_URL` is your web address without `/api/backend`	A message giving the value with `/api/backend` appended
`ASOBEAST_API_URL` answers with a redirect	A message naming the address it redirected to. The token is never sent across a redirect
The token was rejected	A `401` message telling you to mint a fresh token in Settings and to check that the URL is the instance the token was minted on
The account is not entitled	A message that the trial expired or a plan is required

Diagnostics go to stderr, because on stdio the JSON-RPC stream owns stdout. The token is never logged. When the preflight passes, the server logs the instance it connected to and the tools appear in your client.

Troubleshooting

MODULE_NOT_FOUND on startup

The entrypoint path is relative, or the server has not been built. Run pnpm build and register the absolute path to apps/mcp/dist/index.js.

Invalid configuration: : Invalid input from claude mcp add-json

The command was given a whole configuration file. Pass only the server entry, the object that starts with "type": "http", as the Claude Code JSON tab shows.

spawn npx ENOENT in Claude Desktop

Claude Desktop does not read your shell PATH, so it cannot find npx when Node was installed by a version manager. Install Node system wide, or set command to the absolute path that which npx prints in your terminal.

The server shows but has no tools

The entry is nested one level too deep, usually an mcpServers object pasted inside an existing mcpServers object. Keep a single mcpServers key with asobeast directly inside it.

spawn node ENOENT

Desktop clients such as Claude Desktop do not read your shell PATH, so they cannot find node when it was installed by a version manager. Set command to the absolute path that which node prints in your terminal.

The process exits immediately

The preflight failed. Read the stderr output in your client’s MCP log, which names the exact cause: a missing token, a rejected token, or an unentitled account.

The tools do not appear in the client

The client did not start the process, or it exited during preflight. Confirm the command runs on its own in a terminal with the same environment variables, which surfaces the error directly.

The agent cannot reach localhost

The agent is on a different machine than the instance. localhost there means that machine. Set ASOBEAST_API_URL to your public web origin plus /api/backend, or use the hosted endpoint instead, which needs no local process at all.

Connecting spends requests from the MCP budget

A client configured to probe for the newer protocol revision sends one server/discover request before anything else, and it counts against your workspace’s mcpRequestsPerMinute budget like any other request. Connecting and listing the tools costs two requests, so a client that reconnects often spends more of the budget than one that stays connected. See Rate limits and quotas.

The hosted endpoint answers 401, 402, 403, 405 or 429

Each one is a different problem. A 401 means the token is missing, revoked or expired, and it carries a WWW-Authenticate: Bearer challenge. A 402 means the workspace has no live plan. A 403 means the workspace is suspended. A 405 means the client used GET or DELETE, which a stateless server does not offer. The response names POST in its Allow header, and a conforming client carries on over POST. A 429 means a rate limit is spent, and the response says when it reopens. See Rate limits and quotas.

The endpoint has no OAuth. The client did not send the token, so it answered 401 and the client went looking for OAuth metadata, which every /.well-known path on your instance answers with a JSON 404. Check that the header is named Authorization, that its value starts with Bearer followed by the asob_ token, and, for a .mcp.json that reads the token from a variable, that the variable is exported in the shell that starts the client.

MCP tool reference

Every tool and its parameters, generated from the catalog.

MCP recipes

Prompts that work well once you are connected.

​Connect to the hosted endpoint

​The quick path for the stdio server

​The manual path

​Client configuration for stdio

​Choosing ASOBEAST_API_URL

​Verify the connection

​Troubleshooting

​Related

MCP tool reference

MCP recipes

Connect to the hosted endpoint

The quick path for the stdio server

The manual path

Client configuration for stdio

Choosing ASOBEAST_API_URL

Verify the connection

Troubleshooting

Related