Connecting an agent
Machine agents (Hermes, scripts) connect to the Arkana MCP server with a Sanctum bearer token on the agent endpoint, which is reachable only inside the VPC:
| Environment | Agent endpoint |
|---|---|
| Production | https://arkana.byvolare.com/mcp/arkana-agent |
| Staging | https://arkana-staging-1.byvolare.com/mcp/arkana-agent |
| Local | http://localhost/mcp/arkana-agent |
Inside the VPC the Arkana host resolves to the internal load balancer; the
public load balancer refuses this path. People do not use tokens: they sign in
with their Arkana account on /mcp/arkana (see
Use it from Claude Desktop). Each agent gets its
own service user and token.
Issue a token
Section titled “Issue a token”From backend/:
./vendor/bin/sail artisan mcp:agent-token hermes- Creates (or reuses) the service user
hermes@agents.volare.internal. It has no role, so it cannot sign in to the admin panel. - Gives it the
*permission (the admin wildcard) and issues a token namedmcp-hermeswith themcp:*ability. It is not Sanctum’s*ability, so the token cannot call the REST API.
The token reaches every tool, including tools added later: a new tool needs no new token. The token is printed once; store it in the agent’s secret store straight away.
Tokens never expire by default; revoke them when the agent no longer needs
access. Pass --expires-in-days=N for a token that stops working after N days.
The command then prints the expiry date; issue a new token before it (see
below), or the agent starts getting 401 Unauthorized.
Connect Hermes or another agent
Section titled “Connect Hermes or another agent”Any MCP client that speaks Streamable HTTP and can send a header works. Point it at the agent endpoint and send:
Authorization: Bearer <token>For Hermes, keep the token in its .env Parameter Store entry
(/volare/<env>/hermes/env) as ARKANA_MCP_TOKEN and reference it from the
mcp_servers entry in its configuration.
Requests are throttled to 120 per minute.
Revoke
Section titled “Revoke”./vendor/bin/sail artisan mcp:agent-token hermes --revoke--revoke deletes all of the agent’s tokens. To rotate, revoke and then issue
a new token.
Inspect
Section titled “Inspect”./vendor/bin/sail artisan mcp:inspector mcp/arkana-agentOpens the MCP Inspector against the server. Send the bearer header from the Inspector to list the tools a token gets.
Source: backend/app/Console/Commands/McpAgentTokenCommand.php