Federation Agent Setup — raw technical reference

1. Control plane: how the agent issues admin operations

Every operation below is admin GraphQL against a specific instance. There are two ways to invoke it; the rest of the document is path-agnostic.

2. Privacy model

The unit is an agent with its own knowledge base (a trip2g instance). Tiers:

• private — the default. A note with no subgraph should land in private (via the patch in §5.1) and be visible only to the agent/admin itself.
• shared — the common pool for colleagues. A note with subgraph: shared is deliberately shared. This is also the default scope of federation links.
• oversight — selected readers (management/security) read everything, including private, through links whose scope includes private.

Default topology (low ceremony):

• agents are connected through hub(s) over shared (instead of an N² direct mesh);
• one or a few oversight readers with scope = all subgraphs.

There can be several hubs (e.g. per department); hubs may federate to each other (subject to the depth limit, §8).

3. Access semantics — MUST read

When a federated peer (with a kid) reads a note, trip2g checks (canreadnote/resolve_with_subgraphs.go, allowed = the subgraphs in that kid's scope):

1. note free:true            → ALWAYS readable (public)
2. len(allowed) == 0         → NOTHING (except free). Empty scope = NO access
3. note with no subgraphs    → readable by ANY peer with a non-empty scope   ← IMPORTANT
4. note subgraph ∈ allowed   → readable
5. otherwise                 → not readable

(There is also a nuance in the code: if any of the note's subgraphs is flagged requireSignin, a signed-in reader is allowed — rarely relevant to federation setup, listed here for completeness.)

Two consequences that drive the whole setup:

• (rule 3) A note with no subgraph is visible to any peer with any non-empty scope. So "private by default" holds ONLY when the default-private patch (§5.1) is installed. Without it, granting someone shared also exposes every untagged note. The default-private patch is load-bearing, not optional.
• (rule 2) Empty scope = no access, NOT "full access". "Read everything" is expressed by enumerating subgraphs in the scope (including private); there is no wildcard.

free:true is a separate axis: it makes a note public regardless of subgraphs. For a private internal hub, don't use free on knowledge notes (only, optionally, on the hub's KB-notes themselves — see §5.5).

4. Exact GraphQL signatures (reference)

All admin (cookie bypass via §1). Source: internal/graph/schema.graphqls.

Federation secrets:

# inbound: "someone may read me". kid is REQUIRED; secretHex optional (empty → server generates).
createInboundFederationSecret(input: { kid: String!, description: String, secretHex: String })
  -> { id, kid, secretHex }     # secretHex shown ONCE

# outbound: "I may read a peer".
createOutboundFederationSecret(input: { kid: String!, secretHex: String!, kbURL: String!, description: String })
  -> { id }

# inbound secret scope: which subgraphs the peer sees under this kid (allow-list).
addFederationSecretSubgraph(input: { kid: String!, subgraphID: Int64! }) -> { success }
removeFederationSecretSubgraph(input: { kid: String!, subgraphID: Int64! }) -> { success }

revokeFederationSecret(id: Int64!) -> { revokedId }   # select __typename if you don't need revokedId

Subgraphs (read):

allSubgraphs -> AdminSubgraphsConnection { nodes { id, name, color, hidden, requireSignin } }

A subgraph is auto-created when a note carrying subgraph: <name> reaches the instance (there is no separate create mutation). See §5.2.

Notes (write) — creates/updates notes, including arbitrary frontmatter:

updateNotes(input: { changes: [ { upsert: { path: String!, content: String! } } ] }) -> { ... }
# admin via cookie passes (checkapikey admin-bypass). X-Api-Key not needed under cookie admin.

Frontmatter patches:

allFrontmatterPatches -> { nodes { id, includePatterns, excludePatterns, jsonnet, priority, description, enabled } }
createFrontmatterPatch(input: {
  includePatterns: [String!]!, excludePatterns: [String!], jsonnet: String!,
  priority: Int!, description: String!, enabled: Boolean!
}) -> { frontmatterPatch { id } }
updateFrontmatterPatch(input: {...}) ; deleteFrontmatterPatch(input: { id })

Federation (read your own secrets):

federationSecrets -> [ { id, kid, kbUrl, description, createdAt, revokedAt, subgraphCount } ]

(kbUrl != null → outbound; kbUrl == null → inbound.)

Aggregated (if the panel endpoint exists): GET /_system/federation/admin returns self + subgraphs + inbound/outbound with scope + KB-notes in one call (tool instance_federation).

5. Operation recipes

Each recipe = what to call + verification. All calls go through §1.

createFrontmatterPatch(input: {
  includePatterns: ["**/*.md"],
  excludePatterns: [],
  priority: -100,                 # applied first
  enabled: true,
  description: "agent:default-private",
  jsonnet: "if std.objectHas(meta, \"subgraph\") || std.objectHas(meta, \"subgraphs\") then {} else { subgraph: \"private\" }"
})

updateNotes(input: { changes: [ { upsert: {
  path: "subgraphs/shared.md",
  content: "---\nsubgraph: shared\n---\nPolicy: put here knowledge that colleagues' agents should find. Everything else stays private by default."
} } ] })

addFederationSecretSubgraph(input: { kid: "OVERSIGHT", subgraphID: <private.id> })
addFederationSecretSubgraph(input: { kid: "OVERSIGHT", subgraphID: <shared.id> })
# ... + the instance's remaining subgraphs

revokeFederationSecret(id: <id>)                          # full revoke
removeFederationSecretSubgraph(input: { kid, subgraphID }) # remove one subgraph from scope

6. Default "team" setup (low ceremony)

The sequence the agent runs across the pool (via list_slots):

1. On EVERY instance: §5.1 default-private (otherwise the model is leaky).
2. On EVERY instance: §5.2 the shared subgraph with a policy.
3. Pick hub(s) H. For each member M: §5.5 (M↔H over shared).
4. (Optional) Oversight O: §5.6 on all instances (scope = all subgraphs).
5. Verify: §5.8 everywhere; on the hub federated_search returns members' shared.

Result: everything private by default; shared visible to the team via the hub; oversight sees everything; nobody touched keys by hand.

7. instance_federation / GET /_system/federation/admin contract

Aggregated read (admin-only), one JSON:

{
  "self":     { "name", "kb_id", "mcp_url", "subgraphs": [ {id,name} ] },
  "outbound": [ { "id","kid","kb_url","revoked_at","subgraphs":[{id,name}] } ],
  "inbound":  [ { "id","kid","revoked_at","subgraphs":[{id,name}] } ],
  "kb_notes": [ { "kb_id","kb_url","description","path" } ]
}

Used by visualization (the simplepanel graph) and by the agent for verification (§5.8).

8. What depends on the deployment

• Fan-out depth — MCP_FEDERATION_MAX_DEPTH (default 3). Limits hub→hub→member chains and prevents loops. Plan multi-level hubs against the limit. See selfhosted.
• Per-peer timeout — MCP_FEDERATION_FANOUT_TIMEOUT (default 2s). Slow/unreachable peers are skipped.
• Default kb_id = host of the instance's public URL (override with mcp_federation_kb_id in the KB-note). Public URL is instance config.
• Transport — HMAC-SHA256 only, JWT exp ~30s, no mTLS/OAuth, no replay cache. TLS is not enforced by the hub — use HTTPS peer URLs in production.
• Control plane — path §1.1 requires a deployed simplepanel with the pool master secret; §1.2 requires a key with enable_mcp_admin_tools. Without either, configuration is manual.
• free:true and public sites — see the caveat in §5.1.

9. Future: a thin CLI

After this playbook is battle-tested, a thin CLI (python/js, minimal dependencies) makes sense — a wrapper over instance_graphql_request/graphql_request with ready subcommands (default-private, make-shared, link, hub-join, oversight, status). It cuts tokens and agent error rates: short commands instead of long GraphQL strings. Build it after "it works, now final fixes" on the core playbook.

10. Link map (trip2g.com/docs)