KnowledgeConnection

When to use itCopy Anchor Link

Use a KnowledgeConnection when engineers keep the information a change needs outside the repository: design pages, runbooks, ticket history. The context resolver searches these sources and assembles a bundle for each stage. The connection is the only way it can do so, and the org is the only scope that can create one. For the end-to-end flow, see connect knowledge, the context resolver and knowledge and MCP.

Scope and merge rulesCopy Anchor Link

KnowledgeConnection is org-scoped only. The loader refuses any metadata.scope other than SCOPE_ORG, and the profile context refuses one loaded below the org. A repository can only name a connection in its adapter selector (ports.knowledge) when the org has granted it; it cannot define its own.

Three fields carry the FORBID merge directive: endpoint, auth and oauth. Only the org sets them, since they decide where reads go and under which authority.

Field referenceCopy Anchor Link

The two auth modesCopy Anchor Link

KNOWLEDGE_AUTH_USER_DELEGATED runs a search or fetch under the grant of the human who triggered the change. KNOWLEDGE_AUTH_SERVICE_ACCOUNT is for unattended runs. The schema notes that the broker issues a service-account handle only with an approval record, that its effective scope is the intersection of the account's grant and the policy's allowed spaces and projects, and that whether the first release allows it at all is an open design question. Prefer user-delegated until your policy says otherwise.

Working exampleCopy Anchor Link

apiVersion: numinance.dev/v1
kind: KnowledgeConnection
metadata: {name: confluence-eng, scope: SCOPE_ORG}
spec:
  provider: dev.numinance.official/bridge-mcp
  endpoint: https://mcp.example.com/v1/mcp
  auth: KNOWLEDGE_AUTH_USER_DELEGATED
  pinned_tools:
    - {name: searchConfluenceUsingCql, hash: {value: "sha256:3f1a9c0e5b7d2a4f6e8c1b3d5a7f9e2c4b6d8a0f1e3c5b7d9a2f4e6c8b0d1a3f"}}
    - {name: getConfluencePage, hash: {value: "sha256:9b2d4f6a8c0e1b3d5f7a9c2e4b6d8f0a1c3e5b7d9f2a4c6e8b0d2f4a6c8e0b1d"}}
  read_only: true
  scope: [ENG, PAY]
  budgets: {calls_per_stage: 8, bytes_per_call: 65536}
  cache_ttl: 2592000s

A second example in the same directory shows the OAuth variant, which replaces nothing about the read-only rule:

apiVersion: numinance.dev/v1
kind: KnowledgeConnection
metadata: {name: confluence-oauth, scope: SCOPE_ORG}
spec:
  provider: dev.numinance.official/bridge-mcp
  endpoint: https://mcp.example.com/v1/mcp
  auth: KNOWLEDGE_AUTH_USER_DELEGATED
  oauth: {client_id: "https://numinance.example.com/oauth/client.json"}
  pinned_tools:
    - {name: getConfluencePage, hash: {value: "sha256:9b2d4f6a8c0e1b3d5f7a9c2e4b6d8f0a1c3e5b7d9f2a4c6e8b0d2f4a6c8e0b1d"}}
  read_only: true
  scope: [ENG]

How it behaves in the designed runtimeCopy Anchor Link

Security implicationsCopy Anchor Link

• No secrets in the file. There is no field for a token, and the schema is strict, so adding one is an error (shown below). The broker holds secrets and issues a handle. extensions must not hold credentials, endpoints, tool mappings or caps either.
• Pins are the trust boundary, not the endpoint. An https URL tells you the transport, not that the server is the one you approved.
• The endpoint rule excludes IP literals, single-label hosts and .local, .internal or .localhost suffixes, which narrows server-side request forgery, but the egress allow-list is the real control.
• scope is passed as a parameter, never as query text. Do not rely on it to hide documents the delegated user can already read.
• A passing numi validate --files does not check that a pin matches a real tool, that the host is allow-listed or that the provider is installed.

Common misconfigurationsCopy Anchor Link

$ numi validate --files bad/doc.yaml      # read_only: false
invalid  file "doc.yaml": kind: invalid: a value of numinance.kinds.v1.KnowledgeConnectionSpec.read_only fails its check
(exit 3)

$ numi validate --files bad/doc.yaml      # endpoint: http://mcp.example.com/...
invalid  file "doc.yaml": kind: invalid: a value of numinance.kinds.v1.KnowledgeConnectionSpec.endpoint fails its check
(exit 3)

$ numi validate --files bad/doc.yaml      # endpoint: https://10.0.0.5
invalid  file "doc.yaml": kind: invalid: a value of numinance.kinds.v1.KnowledgeConnectionSpec.endpoint fails its check
(exit 3)

$ numi validate --files bad/doc.yaml      # metadata.scope: SCOPE_REPO
invalid  file "doc.yaml": kind: invalid: KnowledgeConnection is org-scoped only
(exit 3)

$ numi validate --files bad/doc.yaml      # scope: ["*"]
invalid  file "doc.yaml": kind: invalid: a value of numinance.kinds.v1.KnowledgeConnectionSpec.scope fails its check
(exit 3)

$ numi validate --files bad/doc.yaml      # auth line removed
invalid  file "doc.yaml": kind: invalid: numinance.kinds.v1.KnowledgeConnectionSpec.auth is empty
(exit 3)

$ numi validate --files bad/doc.yaml      # a hash of "sha256:abc"
invalid  file "doc.yaml": kind: invalid: a value of numinance.kinds.v1.Digest.value fails its check
(exit 3)

$ numi validate --files bad/doc.yaml      # an added "token: abc"
invalid  file "doc.yaml": kind: does not match the kind schema: schema: value does not match (violations: 1): \"/spec/token\": additionalProperties
(exit 3)

Error messages name a field and never echo the value, by design, so a rejected document cannot leak what it contained into logs.

Next stepsCopy Anchor Link