MCP Federation — Personal Router Across Knowledge Bases

Trust model

A federation secret is an HMAC-SHA256 key shared between two peers (or between a hub and an adapter). The base side stores it in federation_secrets and links it to a list of allowed subgraphs in federation_secret_subgraphs. The hub side stores the same secret to sign outbound JWTs to that base.

If federation_secret_subgraphs has no rows for a given kid, that secret authorizes only the public layer of the base (everything canreadnote.Resolve approves for a guest). Adding a row opens up one more subgraph. No row = no privilege beyond anonymous; the secret never grants less than public access.

Schema

-- Trusted HMAC keys for federation. Same row pattern works for both inbound
-- (verify) and outbound (sign): kb_url IS NULL → inbound, NOT NULL → outbound.
create table federation_secrets (
  id           integer primary key autoincrement,
  kid          text not null,                       -- short id placed in JWT header
  secret_crypt blob not null,                       -- HMAC bytes, encrypted at rest
  kb_url       text,                                -- non-null = OUTBOUND (sign for this URL)
                                                    --     null = INBOUND  (verify only)
  description  text,
  created_at   datetime not null default current_timestamp,
  created_by   integer not null references admins(user_id) on delete restrict,
  revoked_at   datetime
);
create index idx_federation_secrets_kid on federation_secrets(kid);

-- Inbound scope. Each row: "kid X may surface my subgraph Y".
-- No rows → kid is anonymous-equivalent on this base.
create table federation_secret_subgraphs (
  kid          text not null,
  subgraph_id  integer not null references subgraphs(id) on delete restrict,
  created_at   datetime not null default current_timestamp,
  created_by   integer not null references admins(user_id) on delete restrict,
  primary key (kid, subgraph_id)
);

subgraphs table is unchanged. No kb_url column, no kid-prefix encoding — that's marketplace-mode complexity, not needed here. The hub just stores secrets and forwards calls; nothing on the hub side maps remote subgraphs to local rows because we're not selling them.

JWT

Header: {"alg": "HS256", "kid": "<federation_secrets.kid>", "typ": "JWT"}

Claims:

{
  "iss": "https://my.hub.local/_system/mcp",
  "iat": 1234567890,
  "exp": 1234567920,           // 30s TTL, 5s skew
  "rid": "req-abc-xyz"          // request id for log correlation
}

Minimal. The kid + signature ARE the identity assertion; the secret was given to a specific peer out-of-band, so possession proves trust. No sub, sgr, or ver in MVP.

What the hub does on outbound

For a federated_* call on KB-note with mcp_federation_kb_url = U:
  secret = SELECT * FROM federation_secrets
           WHERE kb_url = U AND revoked_at IS NULL
           ORDER BY created_at DESC LIMIT 1
  if secret is null:
    proxy U without Authorization header (public base)
  else:
    jwt = sign({iss, iat, exp=+30s, rid}, decrypt(secret.secret_crypt), kid=secret.kid)
    proxy U with Authorization: Bearer <jwt>

What the base does on inbound

1. Read Authorization header.
2. If missing: treat as anonymous → only public layer (canreadnote with guest token).
3. Else parse JWT, look up federation_secrets by kid (kb_url IS NULL, revoked_at IS NULL).
4. Verify HMAC with constant-time compare. Bad signature → 401.
5. Check exp/iat with 5s skew. Expired → 401.
6. allowed = SELECT subgraph_id FROM federation_secret_subgraphs WHERE kid = ?
7. Filter result set: notes that pass canreadnote-with-guest-token
                       ∪ notes whose subgraphs ∩ allowed ≠ ∅.
8. Return.

The same canreadnote logic (intersection on subgraph names) is reused — federation just substitutes a precomputed allowed set for what would otherwise come from ListActiveUserSubgraphs(user_id). Add one sibling helper next to canreadnote.Resolve that takes a precomputed set and skips the user lookup.

Setup walkthrough (per peer)

1. Bob: create the secret on Bob's base. Admin form: pick a kid (alice-2026), generate fresh secret bytes, set scope (which Bob's subgraphs Alice may see — say team-status).
2. Bob: send (kid, bytes) to Alice out-of-band (Telegram).
3. Alice: paste in admin as outbound (kb_url=https://bob.team.io/_system/mcp, kid, bytes). Encrypted at rest.
4. Alice: create KB-note in her vault with mcp_federation_kb_url: https://bob.team.io/_system/mcp. Optionally place it in a subgraph that gates KB-note visibility if she has multi-user concerns (she usually doesn't).

Alice is now wired to Bob. To wire bidirectionally, Alice creates her own secret for Bob and they repeat. Each pair manages its own keys — there's no central registry.

Public-base case

KB-note with mcp_federation_kb_url: https://philosophers.example.com/_system/mcp and no federation_secrets row. Hub proxies anonymously. Public base returns its guest layer. Done.

Revocation

delete from federation_secret_subgraphs where kid = ? and subgraph_id = ?;     -- shrink scope
update federation_secrets set revoked_at = current_timestamp where kid = ?;    -- kill the secret

The hub keeps trying; subsequent calls hit 401. Hub admin notices via warn-level logs. No coordination needed.

Implementation notes

• secret_crypt reuses trip2g's master-key encryption (same primitive as Telegram client tokens).
• All HMAC compares use subtle.ConstantTimeCompare.
• No jti replay cache — 30s TTL is enough for now.
• Inbound auth applies to federated methods only; local search/similar/note_html keep their existing public/authenticated behavior.

Protocol contract

An adapter implements the same six MCP methods. A bare minimum is:

• search(query) — returns results in trip2g's SearchResultPayload shape, with note_id, title, url, score, snippet. Items don't need to be markdown notes — they can be GitHub issues, Telegram messages, Notion blocks, anything that can be addressed by a stable id.
• note_html(pid) — returns HTML or plain text content for one item. For a GitHub issue, that's the issue body + comments. For a Telegram message, the rendered text + media descriptors.
• similar(pid) — optional; if not implemented, return an empty result set.

Adapters that surface authenticated content reuse federation_secrets / federation_secret_subgraphs exactly the same way trip2g bases do. The "subgraph" on an adapter is whatever logical slice it exposes — a GitHub repo, a Telegram channel, a Notion workspace.

Two concrete adapters in scope

GitHub adapter (separate repo / binary):

• Subgraphs map to (org, repo) pairs.
• search queries the GitHub API across configured repos.
• note_html fetches an issue body, PR description, or wiki page by id.
• Auth: a federation secret per hub. Each kid's scope lists which repos it can see.
• The adapter holds GitHub PATs / app tokens internally; trip2g hubs never see them.

Telegram adapter (separate repo / binary):

• Subgraphs map to channels or saved-message buckets.
• search over indexed message history.
• note_html fetches a message + thread by id, rendered as HTML.
• Auth: a federation secret per hub. Each kid's scope lists which channels it can read.
• The adapter holds Telegram session credentials internally.

These adapters live outside the trip2g codebase. This document defines only the protocol surface they must implement to be hubbable. Each adapter gets its own design doc when actually built.

Why adapters use the same auth as bases

So that the hub has one and only one way to authenticate to anything on the federation. No special-casing GitHub vs Telegram vs another trip2g — they're all just "an MCP endpoint with maybe a kid+secret".

Stage 1: MVP

Goal: my hub talks to my own content + 2-3 public bases + 2-3 private peers + 1 adapter (GitHub or Telegram).

1. Schema migration (new db/migrations/...sql):
   • federation_secrets, federation_secret_subgraphs.
2. internal/model/mcp_federation_note.go (new):

   type MCPFederationNote struct {
       Note     *NoteView
       URL      string
       ID       string  // kb_id slug
       MaxDepth int
   }
   func newMCPFederationNote(n *NoteView) *MCPFederationNote { ... }
   func hostnameFromURL(raw string) string { ... }
   

3. NoteViews: add MCPFederationNotes []*MCPFederationNote, populated during finalization.
4. internal/case/mcp/types.go: new arguments (FederatedSearchArguments with KBID/KBIDs; FederatedSimilarArguments; FederatedNoteHTMLArguments). Extend SearchResultItem with URL and Federation *FederationRef. Add Context field to federated payloads.
5. internal/case/mcp/federation.go (new):
   • signOutbound(secret, kid, rid) (jwt string, err error).
   • verifyInbound(jwtStr) (kid string, err error) — looks up federation_secrets, constant-time HMAC verify.
   • proxyToKB(ctx, kb, secret, method, args) (*Response, error) via fasthttp.Client.
   • fanout(ctx, kbs, method, args) []SearchResultItem — parallel with timeout.
   • splitKBID(id) (head, rest string), prefixKBID(localID, results).
6. internal/case/mcp/resolve.go:
   • handleToolsList: always 6 methods.
   • handleToolsCall: dispatch federated_*.
   • handleSearch: mark KB-notes with kind="federation_kb" + federation block. Add URL.
   • handleFederatedSearch / Similar / NoteHTML.
   • accessibleKBNotes(ctx, env, user) filter via canreadnote.Resolve.
7. Inbound auth: middleware on /_system/mcp (or inline in Resolve) that, when an Authorization header is present on a federated_* call, runs verifyInbound and stashes the kid for downstream filtering.
8. Result filtering on inbound: add a sibling of canreadnote.Resolve that takes a precomputed []string of allowed subgraph names. Used by federated handlers when JWT is present.
9. Outbound key lookup: federation_secrets WHERE kb_url = ? AND revoked_at IS NULL ORDER BY created_at DESC LIMIT 1.
10. Admin UI (the bulk of v1 effort, mol widgets):
    • Federation peers list: KB-notes + linked secret status.
    • Add peer: paste kid + secret bytes → encrypt → federation_secrets.
    • Manage scope: list subgraphs, checkbox per kid → federation_secret_subgraphs.
    • Revoke: soft-delete via revoked_at.
11. Tests — see "Test plan" below.

Stage 2: hardening (when needed, not preemptively)

• __visited array for cycle detection (real production data shows it's needed).
• Sub-base response cache.
• Health metrics per peer (latency, error rate).
• Out-of-scope warning round-trip (response carries a warnings array; hub logs).

Stage 3: tooling around federation (post-MVP)

• /_system/mcp/federation discovery endpoint — in marketplace doc; consider if useful even outside marketplace.
• Discovery refresh cron.
• Federation mesh visualization (/_system/federation topology probe).

Stage 4: marketplace

If a real reseller use case appears, see docs/dev/mcp_federation_marketplace.md for the full design. It's additive on top of this MVP.

Reference fixture

                          hub (mine)
            ┌──────────────┼──────────────┬──────────────┐
            │              │              │              │
        public-A       peer-B         peer-C         adapter-X
        (no auth)    (kid=alice)    (kid=alice)    (kid=alice-gh)
                     scope=[team]   scope=[]       scope=[repo1]

• 1 hub.
• public-A: anonymous, returns content for any caller.
• peer-B: requires JWT; kid alice has scope ["team"].
• peer-C: requires JWT; kid alice has empty scope (anonymous-equivalent for this kid).
• adapter-X: GitHub-shaped adapter; requires JWT; kid alice-gh has scope ["repo1"].

httptest.NewServer per node. KB-notes generated programmatically.

Scenarios

Layout

internal/case/mcp/federation_test.go — main file. httptest.NewServer for each fixture node. Existing mocks_test.go reused for unit tests of helpers (splitKBID, prefixKBID, signOutbound, verifyInbound).

Early, clean rejection

Before firing any outbound hop, each node checks incomingDepth + segmentCount(kb_id) against its own max and, if it exceeds, returns a single
unwrapped message kb_id path depth <total> exceeds federation max depth <max>
(internal/case/mcp/federation_handlers.go). Because that sum is invariant
along the path — each hop trades one segment for one depth unit — the entry
node (which sees the full path) rejects up front. No doomed outbound hops fire,
so there is no triple-wrapped federation rpc error -32603: … -32603: …. Blind
fan-out (kb_id="", 0 segments) and cycles that only reveal their depth at
runtime fall through to the header-depth backstop in endpoint.go, which
still bounds them.

Heterogeneous limits across instances

The counter is global to a chain; each instance judges it by its own local max.
Consequences when instances disagree:

• The chain is cut at the first instance whose max < the depth it receives at. The stingiest instance on the path caps everything beyond it — a
  larger limit downstream is useless if an upstream peer already rejected.
• Reachability is route-dependent and asymmetric: the same leaf may be
  reachable through one hub and not through another, purely by which instances
  sit at which positions. This is expected, not a bug.
• Early rejection only enforces the entry node's own max — it cannot know
  downstream peers' limits, so deeper cuts still happen live via the backstop.

Operational guidance: keep mcp-federation-max-depth consistent across a
federation you operate, or monotonically non-decreasing along expected paths
(hub ≥ leaves). Otherwise callers see max depth exceeded that depends on the
route taken.

Prior art

This is the same shape as two well-worn standards. The /-delimited kb_id
resolved hop-by-hop through delegating peers is DNS-style hierarchical
delegation (each instance authoritative for its own zone, aware only of its
direct children); the caller-frame kb_id rewrite on the way back is the
equivalent of qualifying a name toward an FQDN. The depth counter is an
application-layer TTL / Max-Forwards (IP TTL RFC 791; HTTP Max-Forwards
RFC 7231; SIP Max-Forwards RFC 3261) — a per-hop counter that drops a request
when exhausted, with the same inherent, accepted route-dependence.

We deliberately keep our own X-MCP-Federation-Depth header rather than
reuse Max-Forwards. Max-Forwards is a decrementing budget set by the
origin client and defined only for TRACE/OPTIONS; loop protection must be
enforced server-side against the observed depth, or a client could send a
large budget and defeat it. Our incrementing counter judged by each server's
own max cannot be spoofed that way.