A server for AI assistants

MCP stands for Model Context Protocol. It is a shared language between an AI assistant and small programs that do real work. The assistant asks for a named action with named arguments, the program performs it and answers.

ARMANOS ships one such program. It is a single Node file with no third-party dependencies. Your AI tool starts it as a child process and talks to it over standard input and output.

The server does no browsing of its own. Each tool call becomes exactly one HTTP request to the local automation API on 127.0.0.1, the same interface a Python or JavaScript script would use.

So the assistant is not given a new way into your profiles. It is given the way that already existed, with the same token and the same rules.

The tool catalogue is fixed in the server file. Every tool maps to one route the local API already implements, so nothing on the list is a promise for later.

Each tool carries a description written for a model rather than for a menu. It says what comes back and when to reach for it, so the assistant picks a call instead of guessing at one.

Arguments are deliberately narrow. Most tools take nothing at all, the rest take a profileId, and create_profile takes the same fields the New profile form takes.

There is no second store and no export. list_profiles reads the same records the Profiles screen reads, and a profile the assistant creates shows up in the app immediately.

Writes pass through the gate the buttons pass through. A locked licence refuses a launch, and a create beyond your plan quota fails with the reason the app itself would give. The MCP path has no relaxed mode.

A launch answers with the debugging endpoint when one exists. On the ARMANOS Browser each profile gets its own endpoint, so a tool like Puppeteer attaches to exactly that profile. On the built-in engine only the shared app-level endpoint is available, and the answer says so.

• profileId, name, scenario

  The identifiers every other tool takes as its argument.

• group and fingerprintTemplate

  Which group the profile is filed under and which of the five templates it wears.

• proxy summary

  Protocol, host and port. The login and password stay inside the app.

• tags, createdAt, lastUsedAt

  Enough for the assistant to sort and choose without opening anything.

• running

  Whether a window for this profile is open at this moment.

Everything you paste is generated for you. The app knows the script path inside the installation, the address the API is really listening on and your current token.

MCP status on the panel follows the API rather than a setting of its own. It reads Ready only while the local API is actually listening, so you never paste a config for a server that is not there.

1. 1

   Turn on the local API

   Open API & MCP in ARMANOS and flip the switch. The chip must read Running and MCP status must read Ready.

2. 2

   Install Node.js

   Your AI tool launches the server with the node command. Without Node.js on this computer the client reports a missing command and nothing else.

3. 3

   Copy the client configuration

   One button copies the whole JSON block, with the script path, the address and the token already filled in.

4. 4

   Paste it and restart the client

   In Claude Desktop: Settings, then Developer, then Edit Config. Other MCP clients read a file of the same shape.

There is no account to create and no key from us. Two environment variables are the entire configuration, and the server reads them once when your AI tool starts it.

If port 50325 is taken by another program, ARMANOS binds a free port instead and says so on the panel. The copied block then carries the port actually in use, not the one that failed.

Regenerating the token takes effect for the API at once. The block you pasted still carries the old token, so copy the block again and restart your client, otherwise every call comes back as 401.

The path in args points inside the installed app. On Linux AppImage builds the app first copies the script next to its own data, because an AppImage mounts under a new temporary folder on every start. A path into that folder would work once and then break in silence.

command

node

args[0]

…/Resources/mcp/armanos-mcp-server.js

env.ARMANOS_API_URL

http://127.0.0.1:50325

env.ARMANOS_API_TOKEN

the token shown in API & MCP

The whole block sits under mcpServers.armanos, the shape most MCP clients read.

Suppose you ask for your three shop profiles to be opened, and for the login code of one of them. The assistant does not know your ids, so it begins by listing.

A launch is allowed ninety seconds, every other call fifteen. Opening a window on the ARMANOS Browser waits for the engine to publish its debugging port, and that takes longer than reading a list.

Nothing is batched or queued inside the server. Each tool call is one request and one answer, so your client's tool log shows exactly what was asked and what came back.

1. 1

   list_profiles

   Reads every profile and matches your words against names, groups and tags.

2. 2

   launch_profile, three times

   One call per profile. Each passes the licence and quota gate and returns its debugging endpoint.

3. 3

   get_one_time_code

   Returns the current six digits and the seconds remaining, for the profile that has a 2FA key stored.

4. 4

   stop_profile

   When the work is done, one call per profile closes its windows and reports how many were closed.

The API listens on 127.0.0.1 and nowhere else. It is off until you switch it on, and the first run writes a random 48-character token into a file created for your account only on macOS and Linux.

Loopback on its own would not be a boundary. The pages you visit run on this machine too, and a rebound domain name can reach 127.0.0.1 as same-origin. So the API refuses any request that looks like it came from a page, before it answers anything at all, including the version.

One honest line about the other end. The server sends nothing to us and needs no internet, but whatever a tool returns lands in your assistant's context. Where that context is processed is a property of your AI tool, not of ARMANOS.

• Bound to loopback

  Another computer cannot reach it, and neither can anything else on your network.

• Token on every call

  Sent as the x-api-token header. Only /status is open, and only to a program on this machine.

• Pages get nothing

  An Origin header, or a Sec-Fetch-Site other than none, or a Host that is not the loopback address, is refused with 403.

• No credentials in answers

  The proxy listing drops passwords, and the profile listing carries protocol, host and port only.

• Codes, not keys

  get_one_time_code returns the six digits and the seconds left. The 2FA secret itself never leaves the app.

The server is written so it never dies on a bad frame, an unreachable API or a malformed reply. Failures resolve into a normal tool error with text the assistant can read to you.

The five megabyte cap matters more than it sounds. A large profile list with long notes can reach it, and an aborted read used to leave the call unresolved forever, which looks exactly like a frozen assistant.

Errors from the API are passed through with their own message rather than reworded. A refusal about a plan limit reaches you as a plan limit, not as a generic failure.