# MCP Gateway Security Model

contextweaver is a local context-compilation and MCP gateway layer. It does
not call an LLM or implement upstream tool side effects, but it can process
tool schemas, tool results, session history, and raw artifacts that contain
sensitive data. Treat its artifact store and diagnostics as sensitive as the
upstream outputs they summarize.

This page describes deployment boundaries. Vulnerability reporting remains in
the repository's
[`SECURITY.md`](https://github.com/dgenio/contextweaver/blob/main/SECURITY.md).

## Data flow

```text
                         schemas / calls
MCP client  <------>  contextweaver gateway  <------>  upstream MCP server
    |                    |          |
    |                    |          +--> tool execution and authorization
    |                    |               remain upstream / host concerns
    |                    |
    |                    +--> artifact store
    |                         raw tool bytes, local and out-of-band by default
    |
    +--> model provider
         bounded ChoiceCards, summaries, selected artifact slices
```

Prompt-visible by default:

- Compact `ChoiceCard` fields, without full input schemas.
- Firewalled summaries and extracted facts.
- Artifact handles and metadata needed for progressive disclosure.
- A selected slice returned by `tool_view` after the client requests it.

Out-of-band by default:

- Raw text, resource, image, and audio bytes stored as artifacts.
- Full schemas until the selected tool is hydrated for execution.
- Context items excluded by budget or sensitivity policy.

Out-of-band does not mean harmless or encrypted. The default gateway uses an
in-memory artifact store in the gateway process. Other adapters can use
filesystem or caller-supplied stores.

## Data contextweaver can touch

- MCP tool names, descriptions, annotations, and input schemas.
- MCP text, structured content, resources, images, and audio handled by the
  adapter.
- Session messages and tool history ingested through provider adapters.
- Artifact bytes, labels, media types, sizes, and handles.
- Catalog and gateway configuration files.
- Routing queries, candidate identifiers, scores, and build statistics.
- OpenTelemetry attributes and metrics when the optional integration is
  enabled.
- Local gateway JSONL diagnostics when `mcp serve --diagnostics FILE` is
  enabled.

MCP annotations such as `readOnlyHint` are untrusted metadata. They may improve
presentation or routing, but must not grant permission or bypass approval.

## Network and egress

The context and routing algorithms do not make model calls and do not require
network access. Data can still leave the machine through surrounding systems:

- The MCP client sends the compiled prompt and tool responses to its configured
  model provider.
- Upstream MCP servers may call remote APIs or databases.
- An enabled OpenTelemetry exporter sends spans and metrics to its configured
  endpoint.
- Package installation requires a package index unless artifacts are already
  cached or installed.
- An explicitly selected token estimator may fetch tokenizer data on first use
  when its cache is cold; the documented fallback remains deterministic.

The default OpenTelemetry emission excludes raw queries, full tool
descriptions, schemas, and prompt content. Enabling
`otel_emit_experimental=True` can add sensitive content and should be limited
to a trusted, access-controlled backend.

The built-in gateway JSONL stream excludes query text, argument values, result
text, prompt text, and artifact bytes. It does include canonical tool and
artifact handles, namespaces, argument key names, sizes, timings, and error
codes. Treat those identifiers as operationally sensitive and restrict file
permissions and retention accordingly.

## Trust boundaries

### Host MCP client

The host decides which model receives context, which MCP server is available,
and whether a user must approve a call. contextweaver does not replace those
controls.

### contextweaver gateway

The gateway narrows discovery, validates selected arguments against the
hydrated schema, dispatches calls to an `UpstreamCall`, and firewalls returned
content. Routing is relevance selection, not authorization.

### Upstream MCP server

The upstream server implements the operation and its side effects. It must
authenticate callers, authorize access, validate business rules, and protect
its own credentials. contextweaver does not verify that a tool described as
read-only is actually read-only.

### Artifact store

The artifact store contains the bytes deliberately kept out of the prompt.
Anyone with process or storage access may be able to read them. A handle is an
address, not a capability token.

## Context firewall limits

The context firewall reduces prompt exposure and token use. It is not a data
loss prevention system or security sandbox.

- Raw bytes can remain in the artifact store after a summary is rendered.
- Summaries and extracted facts can still contain sensitive values unless a
  sensitivity or redaction policy removes them.
- `tool_view` deliberately re-exposes selected artifact content to the MCP
  client and therefore potentially to the model provider.
- The current in-memory gateway store has no TTL, total-size quota, or
  per-handle authorization policy.
- Current selectors accept caller-provided ranges; deployments should use
  narrow selectors and should not assume a built-in maximum response size.
- The gateway does not neutralize prompt injection contained in a tool result.
  The host prompt and execution policy must treat tool content as untrusted.

Artifact TTLs, size limits, bounded views, redaction, provenance, and a view
policy hook are tracked in
[#375](https://github.com/dgenio/contextweaver/issues/375). Until those
controls ship, high-sensitivity deployments should wrap or disable raw view
access in their host integration.

## Non-goals

contextweaver does not:

- Authenticate users or authorize tool execution.
- Call the model or control how it follows instructions.
- Sandbox or attest upstream MCP server processes.
- Guarantee that MCP annotations are truthful.
- Replace secret scanning, DLP, endpoint security, or storage encryption.
- Prevent a malicious or compromised upstream from returning prompt-injection
  content.
- Make an unsafe tool safe merely because it was selected by the router.

## Hardening checklist

- Use upstream MCP servers you trust and keep them patched.
- Register a tool either directly or behind the gateway, not both.
- Enforce user identity, authorization, and side-effect approval in the host or
  upstream server.
- Keep gateway configs, local state, and artifact directories out of version
  control when they contain machine paths or credentials.
- Put secrets in the client's environment/secret facility, not in committed
  JSON or YAML.
- Use sensitivity labels and redaction before prompt rendering; add
  store-before-view redaction when handling regulated data.
- Prefer `json_keys`, short line ranges, or a small `head` selector over whole
  artifact retrieval.
- Restrict filesystem permissions and process access around persistent
  artifact stores.
- Leave experimental OTel content emission disabled unless the exporter is
  trusted for the data class involved.
- Store gateway JSONL diagnostics in an access-controlled path and define a
  retention policy; use `--quiet` only to suppress lifecycle stderr, not as a
  substitute for diagnostics access control.
- Review tool descriptions and results as untrusted input; do not rely on
  `readOnlyHint`, `destructiveHint`, or similar annotations as policy.
- Pin the contextweaver version in managed deployments and review release notes
  before upgrading.

## Deployment questions

Before exposing a gateway to users, answer:

1. Which identities may use each upstream tool?
2. Where are raw artifacts stored, and who can read that location or process?
3. How long may artifacts remain available?
4. Which content is allowed to reach the model provider?
5. Who approves destructive or externally visible calls?
6. Where do OTel spans go, and can that backend hold the same data class?
7. What is the incident path if a summary or view exposes a secret?

If these answers are undefined, the deployment is not made safe by adding a
context firewall.
