Guides

Adding Tools and MCP Servers

A Tool is something an NPC can do rather than say. Nothing is available to an NPC until you grant it, one NPC at a time.

Grant a Tool to an NPC

Open the NPC and go to its Tools pane. Three sections, one save button:

Built in — the Tools every Village has
MCP servers — the servers you have registered
Skills — see Teaching a Skill

Tick what this NPC may use and press Save tools. Behind the pane, GET /api/npcs/:npcId/tools returns your current grants plus everything you could grant, and PUT /api/npcs/:npcId/tools replaces the whole set with what the form submits. Unticking everything and saving revokes everything.

Grants are per NPC by design. There is no Village-wide switch that hands a Tool to everyone, because the grant rows are the only enforcement that actually holds: a Tool nobody granted is a Tool the model never sees.

The built-in Tools

AgentsVille ships two Tools and two grants that each turn on a family of Tools.

Name	What it is
`current_time`	The current date and time in UTC, because the model has no clock
`fetch_url`	Fetches one public `https://` page or endpoint and returns its text
`sandbox`	Turns on the Sandbox Tools — see Using the Sandbox
`memory`	Turns on `remember`, `recall` and `forget` — see Working with Memory

fetch_url runs inside the API server, so it is deliberately narrow: https only, no private addresses, and every redirect re-checked rather than followed blindly. Anything more than reading a public page belongs in a Sandbox.

The built-in list is short on purpose. A built-in is code you cannot inspect, disable at source, or replace; anything that could be an MCP Server should be one.

Register an MCP Server

Settings → MCP servers. Fill in a name, choose a transport, and register it. Registering makes a server available to grant; it does nothing until an NPC is given it.

mcp_server.transport is one of three values:

http — needs a URL
sse — needs a URL
stdio — needs a command, and is Operator-only

The optional Authorization header is encrypted at rest and never returned by any read. The list shows an auth badge when a server has one stored, and that is all you will ever see of it again — to change it, save a new one; to clear it, the API accepts an explicit null.

A URL must be http: or https: and must not point at an address on the server's own network. Both are checked when you save and again when the connection is actually made, because a hostname that passed the first check can resolve somewhere else by the second.

Why stdio is Operator-only

A stdio server runs a command on the host, as the API server — the process that holds the Provider keys and the database connection. A Player who is not the Operator sees the option greyed out as stdio (Operator only), and the route refuses it with NOT_OPERATOR.

Test before you grant

Every registered server has a Test button. It connects, lists what the server offers, and reports back inline:

A failure reports the connection error in the same place rather than as a failed request. The route is POST /api/mcp-servers/:serverId/test — a POST rather than a GET, because it opens a connection and may start a process.

You do not need to grant a server to anyone in order to test it. "Does this work" and "what does it offer" are the two questions you have at this point, and neither should cost an NPC a capability.

What the NPC sees

A granted server's Tools reach the NPC prefixed with the server's name, so two servers that both offer search stay distinguishable:

If a granted server cannot be reached when a turn starts, the NPC is told so in its prompt and can say so, rather than quietly losing an ability mid-answer.

Changing your mind

Removing a server removes every grant pointing at it, in one transaction, so no NPC is left holding a grant that names nothing. The same is true for a Connector, which is an MCP Server underneath — see Connecting Linear, Notion and Jira.