AgentsVille

Concepts

MCP Servers

An MCP Server is an external process or endpoint that offers Tools over the Model Context Protocol. You register it once on the Village, then enable it on whichever NPCs should have it.

MCP is how AgentsVille gets abilities it does not ship with. If something speaks MCP, an NPC can use it, and you did not have to deploy any code to make that true.

Registering one

A server has a name, a transport, and the details that transport needs:

  • http and sse take a URL, and optionally headers — usually an API key or bearer token. Any Player may register these.
  • stdio takes a command and its arguments, and runs that command on the host. Only the Operator may register a stdio server, because it executes as the Village's own server process — the one holding the provider keys and the database connection.

A URL has to be http or https and has to point somewhere outside the Village's own network. A server pointed at an address on the internal network is refused when you save it, and checked again when it is actually connected to.

Test before you grant

Registering a server does not give it to anybody. Test the connection first: the test connects, lists every Tool the server offers, and shows you the names and descriptions before a single NPC has it.

A failed test comes back as a plain message explaining what went wrong — a bad URL, a rejected token, an unreachable host — rather than as an error page. Read the tool list before granting. It is the cheapest moment to notice that a server offers a delete_everything you were not expecting.

Enabled per NPC

A registered server sits idle until you enable it on an NPC. There is no implicit availability: the NPCs that have it are exactly the ones you ticked.

Tool names are namespaced by the server's name, so a server called "Docs" offering search reaches the model as docs__search. Two servers both offering search therefore do not silently overwrite each other, and you can tell from the transcript which one was called.

If a server cannot be reached when a turn begins, the NPC is told so and says so if asked, rather than quietly answering as though the ability never existed.

Credentials

Headers are encrypted before they are stored, and they are never returned by any read. Reopening a server's settings shows you whether headers are set, not what they are — a field that is sometimes a secret and sometimes a placeholder is a field somebody eventually saves back over the real value.

Encryption uses the Village's BETTER_AUTH_SECRET. Rotating that secret makes every stored credential unreadable and they must be entered again; see Rotating secrets.

Removing one

Deleting an MCP Server also removes every per-NPC grant that pointed at it. There is no second cleanup step and no NPC left holding a grant for a server that no longer exists.

When there is no server for it

There does not have to be. Connectors are pre-configured MCP Servers for common services, with the credential handling already done — connecting Linear or Notion is an authorization flow rather than a URL and a token.

Next