Connectors

The Connectors page (/admin/connectors) manages the remote Pia Mesh pods this server can reach. A connector row describes one MCP tool source; while that source is reachable and granted to a group, its tools are offered to the model on chat requests from members of that group.

Nothing on this page reaches a desktop client. Connector rows stay out of the plugin catalog, out of sync, and off every client-facing surface.

Building the pod on the other end of a row is a developer’s job, not an administrator’s: Writing a pod is the contract to hand them.

The list

Four tiles head the page:

Tile	Reads
Total connectors	Rows that exist
Active	Rows with the Active switch on
Online	Pods currently connected and answering
Not answering	Pods connected but whose last activation could not serve MCP

The last two are meant to be read as a pair — together they are the number of connected pods.

Not answering exists because presence alone lies. A pod whose MCP handling has wedged keeps its uplink connection alive on the transport’s own keepalive, so it stays “connected” indefinitely. This tile reads the session instead: Pia’s liveness probe failed and the reconnect after it failed too. It is a lagging signal — the server learns nothing new until something activates connectors — so a freshly wedged pod may show Online until the next chat request that uses it.

The Presence column expands to show when the pod connected, when it was last seen, and the tools it advertised. For a not-answering pod the tool list is labelled as last-advertised rather than callable, and the cell says when Pia will retry.

The card advertises; the grant authorises

The tool list a pod sends when it connects — its pod card — is an advertisement and nothing more. It grants the pod no access, and it does not decide what the model may call: the group grant on this row is the authorisation, and the callable set comes from a live tool listing over the session. The two can legitimately differ, which is why the presence cell says advertised rather than promising the tools work. Nothing a pod puts on its card can widen what Pia will do with it.

The Groups column is the answer to “why does this pod do nothing?” — an online pod with no group grant contributes nothing.

Creating a connector

1. Press Create connector, type a name and press Create connector again. The row is created with the uplink transport and a placeholder identity, and you land on its detail page.

2. Under Transport, choose how Pia reaches this pod:

   • uplink — the pod dials Pia. Nothing needs to be inbound-reachable. Continue to step 3.
   • streamable_http — Pia dials the pod. Fill in URL; it must be https, or http on loopback for local development. Skip to Outbound authentication.

3. For an uplink pod, open Pod identity and press Generate token. The token is displayed once. Copy it and store it on the pod — Pia keeps only a thumbprint and cannot show it again.

4. Optionally set a Tool name prefix under Tool invocation. With a prefix of crm, a pod tool called lookup is offered to the model as crm_lookup; the prefix is stripped again on the way back out, so the pod always sees its own names. The prefix must match ^[a-z0-9_]{1,32}$. Use one when two pods would otherwise collide.

5. Adjust Call timeout (seconds) if the default of 30 is wrong for this pod. Allowed range is 1–300.

6. Under Group access, check the groups whose members may use this pod’s tools. This is the only place a connector is granted — the group editor’s plugin picker cannot see connector rows.

7. Press Save changes.

Outbound authentication (streamable_http)

Only an HTTP-transport row can carry outbound credentials. An auth block on an uplink row is rejected rather than ignored: the uplink already authenticates in both directions, so an outbound header there would have nowhere to go.

Three schemes are supported.

Scheme	Sends	Also needs
bearer	Authorization: Bearer <secret>	—
api_key	<header name>: <secret>	Header name
oauth2_client_credentials	Authorization: Bearer <minted token>	Token endpoint, Client ID, optional Scopes

For OAuth, Pia exchanges the client id and secret for a short-lived access token at the token endpoint and refreshes it on expiry — no operator involvement, and no browser. The token endpoint follows the same rule as the connector URL: https, or http on loopback.

A header name for api_key must be a valid HTTP field name and may not be Authorization, Host, Content-Type, Content-Length, Accept or Mcp-Session-Id.

The secret is write-only

Enter it once and press Set secret. It is stored encrypted and never rendered back — there is no reveal. The panel shows the scheme and the first eight characters of a fingerprint, which is enough to confirm two rows share a credential or that a rotation took effect. To rotate, type the new value and press Set secret again; to remove it, press Clear secret.

If the panel says “This secret cannot be decrypted — re-enter it”, the Data Protection keyring that encrypted it is gone. The row fails closed and contributes no tools rather than silently calling its target unauthenticated. Setting the secret again fixes it — see Pod uplink and connector credentials.

Editing a live connector

Which edits reach a running pod, and how:

Edit	Effect
Tool name prefix, Call timeout	Re-read on the next activation and pushed into the live connector
Name	Swapped into the live connector’s descriptor, so collision logs name it correctly
Transport, URL, the auth secret	The open session is discarded and a new one opened — these define which client exists
Group access	Applied on the next chat request that resolves connectors
Active switch, turned off	Applied on the next chat request, and the pod’s live connection is dropped immediately

Rotating a credential and seeing nothing happen would be indistinguishable from an outage, which is why the third row recycles rather than patching in place.

Rotating and revoking

Rotate a pod token with Generate token. The previous token stops working immediately, so the pod will drop until it is restarted with the new one. The page asks for confirmation first.

Revoke a pod by turning off Active, or by deleting the row. Deleting is a soft delete — the row is marked deleted and disappears from the page, and its group grants are dropped in the same transaction, so a row later recreated with the same id starts with no access.

Rotate without the console if you are already at a shell on the host:

docker compose -f docker-compose.prod.yml run --rm pia-server \
  --provision-pod issue-token --connector <connector-id>

Same effect as Generate token, no confirmation prompt, and the new token goes to stdout — so use run --rm rather than up, or it lands in the container log. It is audited as Connector.TokenIssued with the actor cli:--provision-pod instead of an administrator’s email, which is the only trace an out-of-band rotation leaves. On a row that is granted to a group, re-issuing is a substitution primitive and not merely a rotation: read Pod uplink before using it. The --provision-pod reference covers the create verb, which provisions a whole pod in one command.

Either way, a pod connected at that moment has its uplink connection dropped, and its presence entry goes with the disconnect. The pod will keep trying to reconnect on its own backoff; a deleted or inactive row refuses it at authentication, so it stays off. This is the only reason a pod is ever disconnected from the server side — an ordinary save, including a rename or a timeout change, leaves the connection alone.

Audit trail

Every action here writes to the audit log:

Event	Written when
Connector.Created / Connector.Updated / Connector.Deleted	A row is created, saved, or deleted
Connector.GroupsChanged	The group grants are replaced
Connector.TokenIssued	A pod token is generated
Connector.SecretChanged	An outbound secret is set or cleared
Connector.PodConnected / Connector.PodDisconnected	A pod attaches or drops — this is the presence history
Connector.UplinkRejected	A connection attempt failed authentication
Connector.PodCardRejected	A pod authenticated but sent an unacceptable capability manifest

Neither a pod token nor an outbound secret is ever written to the audit log or to a log line. Only a short fingerprint prefix is.

Troubleshooting

The pod shows Offline. It has not connected. Check that the pod is running, that it points at /hubs/pod-uplink on this server’s origin, and that it is using the current token — a regenerated token invalidates the old one immediately. Failed attempts appear as Connector.UplinkRejected.

The pod shows Online but nothing happens in chat. Check the Groups column. An online pod with no group grant contributes nothing. Also confirm the row is Active.

The pod shows Not answering. It is connected but could not serve MCP. Pia retries on the next chat request that uses it, from the time shown in the expanded cell. If it stays that way, restart the pod.

A tool the pod advertises never gets called. Another connector may already own that name — the first one registered wins, and the knowledge base is always registered first. Set a tool name prefix on this row.

A streamable_http row is unreachable. Confirm the URL is https (or loopback http), that the target speaks MCP over streamable HTTP, and — if it needs credentials — that the auth panel does not report an undecryptable secret.