Connect an agent - asobeast

There are two ways to connect. The Settings card writes the configuration for you. The manual path is the same thing typed by hand.

The quick path

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

Claude Code
Claude Desktop
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_…"
      }
    }
  }
}

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. There is no default for the token.

Verify the connection

At startup the server calls /auth/me on your instance before it registers a single tool. Three outcomes end the process with a non zero exit status and a readable message.

Situation	What you see
`ASOBEAST_API_TOKEN` unset or empty	A message telling you to set it to a personal API token
The token was rejected	A `401` message telling you to mint a fresh token in Settings
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.

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.

MCP tool reference

All twenty one tools and their parameters.

MCP recipes

Prompts that work well once you are connected.

​The quick path

​The manual path

​Client configuration

​Choosing ASOBEAST_API_URL

​Verify the connection

​Troubleshooting

​Related

MCP tool reference

MCP recipes

The quick path

The manual path

Client configuration

Choosing ASOBEAST_API_URL

Verify the connection

Troubleshooting

Related