Guides
Connecting Linear, Notion and Jira
A Connector is a service your NPCs can work with — issues, pages, boards — reached without pasting an API key into a prompt. Connecting one makes its Tools available to grant; it does nothing until an NPC is given them.
What ships in the catalogue
Open Connectors. GET /api/connectors/catalogue fills the page, and each
entry says which kind of credential it takes.
The catalogue is short on purpose. Anything not listed is still reachable — register it as an MCP Server with its URL and an authorization header, which is all a catalogue entry reduces to anyway. See Adding Tools and MCP Servers.
First, the Operator registers an OAuth client
AgentsVille cannot ship client credentials for somebody else's service, so each
OAuth Connector reads its own pair from the root .env:
The name is always CONNECTOR_ plus the kind in capitals, so the third pair is
Jira and Confluence.
When you register the client with the service, the redirect URI it wants is
PUBLIC_API_URL plus /api/connectors/<kind>/callback. With
PUBLIC_API_URL=https://api.example.com that is:
Restart the server after editing .env. Until both halves of a pair are set,
that Connector is listed with a needs an Operator badge and no Connect
button — shown as unavailable rather than hidden, so a Player can ask for it
rather than wonder where it went.
Connect a service
For an OAuth Connector, press Connect. AgentsVille opens the service's authorization page in a new tab, you approve it there, and the tab lands on a short page saying the service is connected. Close it and go back to the AgentsVille tab you were working in.
For a token Connector, paste the token into the box beside it first. The placeholder tells you where to get one — for Composio, a server created at app.composio.dev; for Sentry, Settings → Auth Tokens.
Finish within ten minutes. The pending authorization is held for that long and then expires, with "That connection attempt has expired. Start it again."
Then grant it to an NPC
Connecting writes an MCP Server behind the scenes. From that point a Connector is not a separate mechanism: go to an NPC's Tools pane, tick the server in the MCP servers section, and save.
Nothing is granted automatically. A Connector you connect and never grant costs you nothing and reaches no NPC.
Status, and what expiry looks like
GET /api/connectors lists what you have connected, with a status badge:
- connected — working
- waiting — an OAuth flow you started and have not finished
- expired — AgentsVille could not renew it
Access tokens are refreshed for you. Before an NPC takes a turn, AgentsVille renews anything close to expiring, so a long-lived connection keeps working without you noticing.
When a refresh fails outright — a revoked authorization, a rotated client secret — the Connector is marked expired and its MCP Server is disabled, so no NPC is handed a dead service mid-answer. The page says what to do: disconnect it and connect it again.
Disconnect
The trash button beside a connected service calls
DELETE /api/connectors/:connectorId. It removes the underlying MCP Server and
every per-NPC grant pointing at it, in one transaction. Access stops
immediately and nothing is left behind pointing at a service you no longer use.
Revoking the authorization on the service's own side is worth doing too; AgentsVille deletes its copy of the credential, it does not speak for your account at the far end.
How the credential is kept
Tokens are encrypted at rest with a key derived from BETTER_AUTH_SECRET, and
no read endpoint returns them — not the list, not the catalogue, not the MCP
Server the Connector created. They do not appear in a Message, in a log, or in
a Tool argument rendered in the transcript.
One consequence worth knowing before you rotate anything: changing
BETTER_AUTH_SECRET makes every stored credential unreadable, and every
Connector has to be connected again. See
Rotating secrets.