Concepts

Connectors

A Connector is a pre-configured MCP Server plus the credentials to reach a third-party service. Connecting Linear, Notion or Jira is a Connector.

A Connector is not a separate mechanism. It is a Tool source with the endpoint already filled in and the credential handling done for you. Once connected, it is an ordinary MCP Server: granted per NPC, its tools namespaced the same way, its calls shown in the transcript the same way. See ADR 0011.

What ships in the catalogue

Five entries, deliberately few:

Service	What it gives an NPC	Credential
Composio	Several hundred apps behind one connection	Token
Linear	Read and file issues, see what is in flight	OAuth
Notion	Search pages, read them, write them back	OAuth
Jira and Confluence	Issues, boards and pages on an Atlassian site	OAuth
Sentry	Look up issues and stack traces	Token

The catalogue exists to save you looking up an endpoint, not to limit what you can connect. Anything absent is still reachable through "Register an MCP server", which takes a URL and a header — which is all a catalogue entry reduces to.

These entries are unverified in the sense that matters: AgentsVille cannot test them without credentials for each service, so the first Operator to connect one is the one who finds out whether that service's endpoint behaves as documented.

Two ways to connect

Paste a token. The service issues one, you paste it, AgentsVille stores it encrypted. Composio and Sentry work this way, and each shows you where to get the token.

Authorize. AgentsVille runs a standard OAuth authorization-code flow with PKCE: you are sent to the service, you approve, you come back connected. No key ever touches a prompt or a form field. Expired tokens are refreshed before a turn begins, so a Conversation does not fail halfway through because a token aged out.

OAuth needs the Operator first

AgentsVille cannot ship client credentials for somebody else's service. Each OAuth Connector reads its own pair from the root .env file:

The redirect URI to register with the service is PUBLIC_API_URL followed by /api/connectors/<kind>/callback — for example https://api.example.com/api/connectors/linear/callback.

A Connector whose pair is not set is shown as unavailable rather than as a button that fails. If you are a Player and a service you want is greyed out, ask your Operator to register a client for it. See Connecting Linear, Notion and Jira.

Credentials are never readable back

Tokens are encrypted at rest with the Village's BETTER_AUTH_SECRET, and no read endpoint returns them. They do not appear in a Message, in a log, or in a Tool argument rendered in the interface.

Rotating that secret makes every stored credential unreadable, and every Connector has to be connected again. See Rotating secrets.

Disconnecting

Disconnecting a Connector removes its MCP Server, and removing the server removes every per-NPC grant that pointed at it. Revoking an NPC's access to your Jira is one action, immediately, with nothing left behind pointing at a service you no longer want reached.

Connecting Linear, Notion and Jira
MCP Servers — for anything not in the catalogue.
Configuration — the OAuth client variables.