Grounded v0.3.0

Image

ghcr.io/ncecere/grounded:v0.3.0
ghcr.io/ncecere/grounded@sha256:23c757c29c74beab26678829d6f31598c1e3543bbf4fef12bc413bf77916b176

Deploy by digest. Verify the signature (keyless, GitHub Actions OIDC):

cosign verify ghcr.io/ncecere/grounded@sha256:23c757c29c74beab26678829d6f31598c1e3543bbf4fef12bc413bf77916b176 \
  --certificate-identity-regexp '^https://github.com/ncecere/grounded/\.github/workflows/.+@refs/tags/v0.3.0$' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

The OCR sidecar (optional, components/ocr-tesseract), signed the same way:

ghcr.io/ncecere/grounded-ocr:v0.3.0
ghcr.io/ncecere/grounded-ocr@sha256:64646a50bc8bf40ce3cf75ec922cfbe7dfa7a53b247081ed4d825586835a6c21

Release assets

• grounded-v0.3.0-<os>-<arch>.sbom.spdx.json: the image's SBOM (SPDX JSON) for each platform, as attached to the image.
• grounded-v0.3.0.digest.txt: the image reference by digest.
• checksums.txt: SHA-256 of the files above (sha256sum -c checksums.txt).

The SBOM and build provenance are also attached to the image as attestations, which the signature covers:
docker buildx imagetools inspect ghcr.io/ncecere/grounded@sha256:23c757c29c74beab26678829d6f31598c1e3543bbf4fef12bc413bf77916b176 --format '{{ json .SBOM }}'.

Grounded v0.3.0

v0.3.0 is about reach. Through the Model Context Protocol (MCP), Grounded works in both directions: other AI tools search its knowledge bases and ask its agents, and its agents call tools on MCP servers a platform admin approved. It also stores the health of models, connections and MCP servers, and can trace one answer end to end with OpenTelemetry. Every new feature is off until a platform admin turns it on or configures it. The full list of changes is in the changelog, and the plan with the owner's decisions is in v0.3.0.md.

A walkthrough by role (platform admin, auditor, team owner and editor, member) came before this release, and its findings were fixed. v0.3.0-rc.1 runs on the reference install before v0.3.0 is tagged.

Highlights

• Grounded as an MCP server (mcp.md). Coding agents and desktop assistants connect to <APP_URL>/mcp (Streamable HTTP, protocol revision 2026-07-28, and older clients back to 2024-11-05) with an API key that has the new MCP scope. Two tools: search returns passages with their titles, headings, links and citation numbers; ask returns an agent's answer with [n] markers, citations and, when SystemOne checks citations, a verdict for each claim. Each tool lists exactly the knowledge bases and agents the key may use. Limits, budgets, classification and the audit log apply as on the REST API. Turn it on under Admin → Overview → Features → MCP server.
• OAuth sign-in for MCP clients (experimental). With it on, a person connects an AI tool by signing in to Grounded in their browser and approving the tool, with no API key to copy. Grounded is a small OAuth 2.1 authorization server for its own /mcp, in front of your sign-in provider. A token acts as the person over their current teams, and nothing on the REST API. Each person sees and disconnects their Connected apps; platform admins see and disconnect anyone's.
• MCP tools in agents (mcp-client.md). A platform admin registers a remote MCP server (Admin → Models → MCP servers), sets the most sensitive data it may receive, reads its tools and approves them one by one after reading their descriptions. Editors choose approved tools under Agent → Build → Tools. During an answer, calls are bounded (timeout, response size, the team's MCP tool calls per answer, at most 25), admitted by the team's budget, metered (optionally priced per call), audited without their arguments or results, and each result is cited as a numbered source that claim checks verify like a passage.
• Stored health (operations/health.md). Every Test of a connection, model or MCP server stores its result, and the worker re-tests enabled ones every 15 minutes at no cost. The lists show "Healthy · 3 minutes ago" or "Failing · since 2 hours ago" with a Health filter; failures appear under Needs attention on the admin Overview; the GroundedHealthCheckFailing alert fires after 30 minutes.
• OpenTelemetry tracing (operations/tracing.md). With OTEL_EXPORTER_OTLP_ENDPOINT set, one answer is one trace across the HTTP request, retrieval, model calls, SystemOne checks, MCP tool calls in both directions and background jobs. Spans carry IDs, counts and durations, never questions, answers, passages or tool arguments.
• Faster answers, and they say what they're doing. An answer's first words come sooner: a follow-up is rewritten into a search query only when it depends on the conversation, the search runs while the question's moderation and scope checks answer, and SystemOne passage judging waits at most a time limit (Admin → SystemOne → Passage judging time limit, 1.5 s by default; passages not judged by then are kept, as if unjudged). Until the first words, the chat says the step: "Understanding the question…", "Searching 's knowledge…", "Checking the passages…", "Writing the answer…" (or "Writing and checking the answer…" when answers are checked before they're shown).
• Reasoning effort. A chat model marked Accepts reasoning effort (Admin → Models → Compatibility) lets each agent choose low, medium or high (Build → Advanced), and query rewrites ask it for low effort. Publish is disabled while the draft has problems publishing would refuse, and says how many.
• A clearer audit log. Each entry says how the person acted: signed in, with an API key or through a connected app, by name. The platform log shows the caller's address. OAuth and tool-call entries say what happened ("App renewed its sign-in", "Connection revoked: a refresh token was reused (possible theft)", "An agent's MCP tool call was refused (call limit)").
• Quieter server errors. A request its client cancelled (a reload, a closed tab) is logged at info and counted as status 499, not as a 500 in the 5xx metrics and the error objective, and every log line uses the configured format.

Requirements

Unchanged from v0.2.0. Tracing needs an OTLP receiver (Tempo, Jaeger or an OpenTelemetry Collector) only if you turn it on.

Upgrading from v0.2.2

A rolling upgrade with no downtime. Take a backup as for any upgrade (operations/upgrades.md), then change every ?ref=v0.2.2 in your overlay to ?ref=v0.3.0 and pin the new digests of ghcr.io/ncecere/grounded and, if you run OCR, ghcr.io/ncecere/grounded-ocr.

Migrations 00035 to 00039 run on start (schema version 34 → 39). They are expand-only, so v0.2.2 pods keep working against the new schema while the rollout proceeds:

Migration	What it adds
00035_mcp_server	The MCP server switch (a new one-row table, off), and mcp in the API-key scope and answer-channel constraints (widened, validated without locking writes)
00036_health_checks	The health_checks table and the health_subjects view
00037_mcp_client	MCP servers, their tools and approvals, the tools of each agent version, the mcp_calls price unit and the mcp_server health kind (new tables; constraints widened)
00038_mcp_oauth	The OAuth sign-in setting (a column on mcp_settings, off) and the OAuth clients, grants, codes and tokens tables
00039_message_retrieval	The retrieval step of an answer (a nullable column on messages), so a reopened answer shows its "Searched the knowledge base for …" step

New settings (all optional; .env.example describes each):

Setting	Default	What it does
HEALTH_CHECK_INTERVAL	15m	How often the worker re-tests enabled connections, models and MCP servers (5m to 24h, or off). It sends no completions, embeddings or tool calls
OTEL_EXPORTER_OTLP_ENDPOINT	unset (tracing off)	The OTLP receiver. Tracing stays off without it
OTEL_EXPORTER_OTLP_PROTOCOL	http/protobuf	Or grpc
OTEL_EXPORTER_OTLP_HEADERS	unset	Headers for the receiver, such as a token (also OTEL_EXPORTER_OTLP_HEADERS_FILE); a secret, never logged
OTEL_SERVICE_NAME	grounded	The service name on spans
OTEL_TRACES_SAMPLER, OTEL_TRACES_SAMPLER_ARG	parentbased_traceidratio, 1.0	Which traces are kept. Invalid values stop the process at start

Kubernetes: the new optional component components/tracing sets the OTLP endpoint (a placeholder to patch) and adds egress to the collector on TCP 4318 (4317 for gRPC) in the monitoring namespace. It isn't in the base. MCP servers are reached through the existing grounded-app-egress-web policy (TCP 80 and 443); a server on another port needs its own egress rule. /mcp, /oauth/… and /.well-known/oauth-… are served by the api pods behind the same ingress, so nothing changes there. The alert rules and dashboards gain the health metrics and GroundedHealthCheckFailing: regenerate your copies if you vendor them.

Things people will notice:

• Admin → Overview → Features has two new rows, MCP server and OAuth sign-in for MCP clients, both off.
• Admin → Models has an MCP servers page, and Connections, Models and MCP servers have a Health column. Existing connections and models show "Not tested yet" until the first scheduled check, a few minutes after the worker starts.
• API keys have a new MCP scope, and people who connect an AI tool through OAuth see it under Connected apps.
• Agent → Build has a Tools section. It only lists tools once a platform admin has approved some, and the agent's chat model must support tools (a platform admin ticks Supports tool calling on the model in Admin → Models).
• Limits → Queries & chat has MCP tool calls per answer (default 5, at most 25), and Costs has an MCP tools spend category.
• The audit log has the areas and actions of the new features (mcp.*, mcp_server.*, mcp_tool.*, oauth.*, platform.mcp, platform.mcp_oauth), and each entry says how the person acted.
• Metrics: new grounded_mcp_tool_calls_total, grounded_mcp_client_calls_total, grounded_mcp_client_call_duration_seconds, grounded_health_failing, grounded_health_failing_seconds, grounded_health_checks_total and grounded_health_check_duration_seconds; the route group mcp, outside the latency objective; and status 499 for requests the client cancelled (operations/monitoring.md).
• API (additive): the MCP server, MCP servers, tool approval, health-check, OAuth consent and connected-app endpoints; tools in agent configurations; kind, server and tool on citations; max on limits; via and clientIp on audit entries. /mcp and the OAuth protocol endpoints are described in mcp.md, not the OpenAPI document.
• Streamed chat: a new status event names each step before the first words, and a model failure after the stream has started arrives as an error event instead of an HTTP 503 (JSON answers and the OpenAI-compatible endpoint are unchanged). Clients that read the stream should handle error events; the web client does.

Known limitations

The v0.2.0 limitations still apply. For the new features:

• OAuth sign-in is experimental and may change while clients and the specification settle. It has no CORS on its endpoints, no private-use redirect schemes (myapp://) and no client secrets. A registered (DCR) client's name and website are its own claims: the consent page marks such clients Unverified.
• MCP tools use static credentials only: a header stored encrypted. OAuth to outside MCP servers isn't supported yet. Only Streamable HTTP servers at public addresses; a host name's addresses are checked when Grounded dials it, not when the server is saved.
• Requests for more input from an MCP server (elicitation, MRTR) are refused: an agent answering a person can't ask a remote server's questions.
• Not in this release: documents as MCP resources, a Teams or Slack bot, trace links from dashboards, and per-stage timings in the product.

Verifying the images

As for v0.2.0, with the tag v0.3.0: docker run --rm ghcr.io/ncecere/grounded@sha256:<digest> version prints grounded v0.3.0 (<commit>), and so does the MCP server's serverInfo.version. Each release has SPDX SBOMs, digest files and a checksums.txt. Tracing adds about 3.5 MB to the binary.

Reporting problems

Report bugs and requests as GitHub issues. Report vulnerabilities privately, as SECURITY.md describes.