Metadata-Version: 2.4
Name: kamiwaza-mcp
Version: 0.1.0
Summary: Hosted MCP server exposing the Kamiwaza platform to AI agents
Author-email: Kamiwaza AI <support@kamiwaza.ai>
License-Expression: Apache-2.0
Project-URL: Homepage, https://www.kamiwaza.ai
Project-URL: Documentation, https://docs.kamiwaza.ai
Keywords: mcp,model-context-protocol,kamiwaza,ai-agents
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: kamiwaza-sdk==1.4.0
Requires-Dist: jsonschema>=4.20
Requires-Dist: mcp<3.0.0,>=2.2.0
Requires-Dist: uvicorn<1.0,>=0.30
Requires-Dist: fastapi<1.0.0,>=0.136.3
Requires-Dist: pydantic<3.0.0,>=2.11
Requires-Dist: starlette<2.0.0,>=1.3.1
Requires-Dist: PyJWT[crypto]>=2.8
Requires-Dist: requests<3.0.0,>=2.33.0
Requires-Dist: kamiwaza-extensions-lib<0.7,>=0.6
Dynamic: license-file

# Kamiwaza MCP server

A [Model Context Protocol](https://modelcontextprotocol.io) server that gives an
AI agent the whole Kamiwaza platform through a tool surface whose size never
changes.

The pinned platform client exposes **439 callable operations** and grows every
release. Publishing one tool per operation would spend thousands of tokens of
every agent's context before it did any work, and tool-selection accuracy falls
as the list grows. This server publishes **21 tools** — four discovery tools plus
17 workflow tools — holds the operation index server-side, and reaches the other
**405 published operations** by search.

Any standards-conformant host can connect. There is no Kamiwaza SDK to install on
the client, no custom transport, no private header, and no bespoke handshake.

## What this server supports

### Protocol revisions

One process serves two revisions, and **each is a separate claim**. A statement
proved for one revision is not a statement about the other: the two arms
negotiate differently, so a conformance result for either has to be read as that
revision's result alone.

| Revision | How a host negotiates it | Session |
| --- | --- | --- |
| `2026-07-28` | Per request. The host declares the protocol version and its client capabilities in that request's own `_meta`; there is no handshake. | None |
| `2025-11-25` | Once, in `initialize`. | None issued — the transport is stateless |

Both are in `SERVED_REVISIONS` (`src/kamiwaza_mcp/protocol/revisions.py`), and
`SERVED_MODERN_REVISIONS` is the modern subset `server/discover` advertises. Any
other revision is refused on **every** method by `revision_gate`
(`src/kamiwaza_mcp/protocol/refusals.py`), and the refusal names this server's
served set rather than every revision the library can speak. An import-time check
in `revisions.py` fails the process if the served set is not one revision from
each era, so the two arms cannot silently become one.

Conformance is asserted per revision, not once for both:
`tests/conformance/test_dual_revision.py` drives both arms of a single
application, `tests/conformance/test_capabilities.py` probes each advertised
capability per revision against the method that implements it, and
`tests/conformance/test_revision_refusals.py` asserts the refusal for everything
else.

### Deployment topologies, and how each is run

The topologies differ in exactly one thing — who established the caller. Both
then build the same protocol server from the same factory (`server/app.py`
`build_server`), which is what makes the published surface identical.

**Hosted, behind the platform edge** (`transport/http.py` `hosted_deployment`):
the edge authenticates the member and forwards the context, so this server
terminates no public edge and holds no edge certificate.

```python
from kamiwaza_mcp.transport.http import hosted_deployment, serve_http

app = serve_http(
    hosted_deployment(platform_base_url="https://kamiwaza.example.com/api"),
    host="0.0.0.0",
    port=8080,
)
```

**Which infrastructure installed it is not this server's business.** The same
image runs under the platform operator, under the legacy deploy
infrastructure, and under plain Compose, because the hosted topology depends on
the forwarded-envelope *contract* and not on what produced it: the member, the
workroom and the caller's token, parsed by
`kamiwaza_extensions_lib.identity.extract_identity` — the platform's own
parser, shared with every other extension — rather than by header names
invented here (FR-034, `tests/conformance/test_implementation_neutrality.py`).

The one place the two planes genuinely disagree is the tenant. The platform's
signed ForwardAuth payload carries no tenant header at all, while the
platform's own services do send `x-tenant-id`. So the tenant is read from the
forwarded credential's claims, which the authorization server signed, and
`x-tenant-id` is only a fallback for a deployment whose tokens carry no tenant
claim — a request with neither is refused, because its isolation scope is
unknown.

Measured against one live cluster, all three ways: through the operator's edge
with the extension installed, through Compose with the header-less envelope,
and in-process with and without `x-tenant-id`
(`tests/integration/test_hosted_live.py`). The published listing is
byte-identical to the standalone one in every case.

**Standalone, as its own protected resource** (`transport/http.py`
`standalone_deployment`): no edge sits in front, so this server validates the
bearer credential itself. The credential verifier is required with no default,
because a standalone deployment that admitted callers without verifying them
would be an open endpoint.

```python
from kamiwaza_mcp.authority.resource_server import (
    PlatformCredentialVerifier,
    ProtectedResource,
)
from kamiwaza_mcp.transport.http import serve_http, standalone_deployment

resource = ProtectedResource(
    resource="https://mcp.kamiwaza.example.com/mcp",
    authorization_servers=("https://auth.kamiwaza.example.com",),
    scopes_supported=("kamiwaza.read",),
    resource_name="Kamiwaza platform",
)
app = serve_http(
    standalone_deployment(
        PlatformCredentialVerifier(
            resource=resource,
            issuer="https://auth.kamiwaza.example.com",
            resolve_signing_key=fetch_signing_key,   # your key-set lookup
            tenant_claim="tenant",                   # required, never guessed
        ),
        platform_base_url="https://kamiwaza.example.com/api",
        resource=resource,
    ),
    host="0.0.0.0",
    port=8080,
)
```

**A host-launched local process** (`cli.py`, over `transport/stdio.py`):
standalone, never hosted. A pipe carries no per-request credential, so the
member is established once — by asking the cluster whose credential the process
was started with — and every call runs as that member. `LocalCredentialAdmission`
refuses a second identity rather than serving it under the first, and refuses to
run with no credential at all.

Installing the package leaves a command behind, which is what a host's launch
configuration names:

```bash
export KAMIWAZA_API_URL=https://kamiwaza.example.com/api
export KAMIWAZA_MCP_CREDENTIAL=<a member's own credential>

kamiwaza-mcp                              # stdio, the default
kamiwaza-mcp --transport http --port 8080 # a loopback listener instead
```

Both variables are required and neither is defaulted: a default cluster address
would be one cluster's address in every other deployment, and this server has no
identity of its own to fall back on. The credential is read from the environment
rather than an argument, because a credential in `argv` is readable by every
process on the machine. Who the process serves is not configuration either — the
credential is presented to the platform's own `auth/users/me` at startup, so a
stale credential fails immediately instead of misattributing calls to a member
somebody typed.

Hosted plus stdio is refused when the deployment is constructed
(`Deployment.__post_init__`): there is no edge in front of a process reading
standard input, so a forwarded context arriving there would be one nothing
produced.

`--transport http` is the local listener of FR-032e: it binds `127.0.0.1` only,
switches on the origin check the library leaves off by default
(`transport/local_guard.py`), and still requires a credential per request.
Measured against a live cluster: a request from an unrecognised origin is
refused with 403 and one carrying no credential with 401.

### Transports

Two, and only two — the `Transport` enum in `authority/admission.py` has no third
member:

- **Streamable HTTP**, served at `/mcp` (`server/app.py` `PROTOCOL_PATH`), built
  `stateless_http=True` so any replica can serve any request.
- **stdio**, for a host-launched local process.

The deprecated **HTTP-with-SSE** transport is **not** served. It is deprecated in
both targeted revisions, so it is neither the default nor a way to reach
anything: nothing mounts it, and the only HTTP application this repository builds
is the Streamable HTTP one.

### Authorization

| Topology | How a caller is established | What this server publishes |
| --- | --- | --- |
| Hosted | The platform edge's forwarded context: `x-user-id`, `x-user-roles`, `x-workroom-id`, `x-tenant-id`, `x-auth-token`. Any field missing is a refusal, and the platform is never reached. | No protected-resource route and no challenge. A challenge here would send a host to authorize directly against this server, past the edge that already refused it. |
| Standalone | A bearer credential this server verifies, audience-checked against its own resource identifier. | The RFC 9728 document at `/.well-known/oauth-protected-resource/mcp`, served **unauthenticated** because discovery is what a caller holding no credential is doing. |

Standalone challenges, per RFC 6750 §3.1 (`server/metadata.py`,
`authority/resource_server.py`):

| Request | Status | `WWW-Authenticate` |
| --- | --- | --- |
| No `authorization` header | 401 | `error="invalid_request"`, plus `resource_metadata` |
| A credential for another audience, or an unverifiable one | 401 | `error="invalid_token"`, plus `resource_metadata` |
| A valid credential missing a required scope | 403 | `error="insufficient_scope"`, `scope="…"`, plus `resource_metadata` |

The 401/403 split is load-bearing rather than cosmetic: a host retries a 401 by
authorizing, and a 403 by authorizing for *more*. A 401 for insufficient scope
would send it round the same flow to arrive at the same refusal.

The discovery path is built by `metadata_path`, which inserts the well-known
segment *before* the resource's own path, so a host asking about `/mcp` is
answered about `/mcp`.

No caller credential is forwarded onward, and this server holds no workload
identity of its own: inbound it validates a platform credential, outbound it uses
the caller's own authority. It refuses rather than escalating.

### The negotiated extension

`io.modelcontextprotocol/tasks` — **optional**, and advertised only when it is
registered. The library derives `capabilities.extensions` from the extensions the
server was constructed with (`server/app.py` passes `deployment.extensions`
through), so the capability map cannot claim an extension whose methods are
unreachable. Its three methods are bound only at the modern revision.

A client that did not declare the extension and calls a task method is refused
with the specification's `-32021` and a `requiredCapabilities` payload naming what
to declare (`protocol/tasks.py`, via the library's `require_client_extension`).
A host that never negotiates it is not locked out of slow work: a workflow call
gets a wait bounded at 45 seconds (`workflows/wait.py`) and an `expired_wait`
outcome carrying the identifier of whatever already exists, so the correct
response is to resume rather than to start a second one. `call_operation` has
no wait budget of its own at this version (`surface/call_operation.py`), so a
slow single operation is bounded by the host's own patience and not by this
server.

A task handle is a sealed reference to the platform's own record, not a row in
this server's memory, so it survives a disconnect and a restart.

## The tool surface

### Discovery

| Tool | Accepts | Returns |
| --- | --- | --- |
| `find_operations` | a plain-language query, optionally a category and limit | candidates with `operation_id` and a one-line summary — never shapes |
| `describe_operation` | one `operation_id` | the input shape, the result shape, the approval requirement, and any workflow hint |
| `call_operation` | an `operation_id` and arguments | the success envelope, a failure envelope, or a task handle |
| `docs` | an optional topic | usage guidance, plus this server's version and the pinned descriptor version |

`docs` answers six topics — `overview` (the default), `entitlement`,
`slow-work`, `failures`, `shapes`, `withheld` (`surface/docs.py`).

### Workflow tools

Seventeen, always published, from the pinned descriptor package
(`workflows/publish.py` `published_workflows`; descriptions are asserted against
the package's own docstrings by
`tests/conformance/test_description_provenance.py`):

| Area | Tools |
| --- | --- |
| Models | `find_and_deploy_model`, `deploy_and_connect_model`, `preflight_and_deploy_model`, `diagnose_deployment`, `retire_deployment` |
| Data | `ingest_dataset_and_index`, `run_source_ingestion`, `complete_dataset_ingestion`, `rag_query`, `enclave_ingest` |
| Federation and access | `pair_federation_and_allow_user`, `grant_subject_access` |
| Gates | `install_and_bind_gate_package`, `replace_gate_package` |
| Workrooms and apps | `create_workroom_and_enter`, `export_workroom_bundle`, `deploy_app_from_garden` |

Each names at most one polling step, bundles at most one approval-bearing step,
and states whether it is idempotent. Sixteen of the seventeen declare an
approval step — every one but `diagnose_deployment`, counted from the pinned
descriptors — and each of those names the change a member is consenting to.
Single destructive acts are deliberately not wrapped: deleting something,
rotating a credential, or uninstalling a package stays one explicit call.

### The listing is the same for every caller

Entitlement is never marked at discovery: the platform authorizes by relation on
an object, and discovery has no object. Two callers receive **byte-identical**
listing, search and shape answers
(`tests/conformance/test_listing_invariance.py`). There is no persona — not as a
parameter, not as a tool set, not as a deployment
(`tests/conformance/test_persona_neutrality.py`).

One posture changes the listing, and no request can reach it: the deployment's
own read-only posture. `Deployment.read_only` withholds every write and every
credential-returning read, taking the published set from 21 tools to 5.

The posture is set by the deployment's own `KAMIWAZA_MCP_READ_ONLY` — declared
in `docker-compose.yml` and defaulted off in `kamiwaza.json`, so an install that
says nothing serves the full surface. With it on, a withheld operation is absent
from `find_operations`, reported as unknown by `describe_operation`, refused by
`call_operation` even when a caller guesses its identifier, and the workflows
that change something are not published at all. A value that is neither on nor
off stops the container at startup rather than being read as off.

A gated act is answered by asking, and the question is the caller's own "do
you want to run this?" rather than a second person's approval. It goes out by
whichever mechanism the connection's revision defines, and it is the same
question either way:

- **`2026-07-28`** — the call returns an awaiting-input result carrying the
  described act and opaque state; the client answers and retries. Nothing is
  held open, so any replica can serve the retry.
- **`2025-11-25`** — the server sends `elicitation/create` inside the call and
  waits for the reply, which is the only mechanism that revision has. It needs
  a connection that keeps a channel back, which stdio has and stateless HTTP
  does not.

A client that declared no elicitation is refused rather than served unasked:
"the host could not be asked" is not a reason to proceed. A client that *did*
declare it but connected without a channel back gets a refusal naming the
channel, because it has already done what a capability refusal would ask of
it. FR-037c records the third carriage — URL mode elicitation, for a client
that can render no prompt at all — as deferred.

A read-only deployment withholds every gated act along with the writes: an
approval marks a privileged result (FR-020), so those acts are absent from
discovery and refused on call.

Thirty-four of the 439 callable operations are **withheld**, each with a stated
reason. A withheld identifier is refused by name and reason rather than reported
as unknown, because "unknown" invites another guess
(`tests/conformance/test_unpublished_set.py`).

### Token cost

Asserted, not estimated — `tests/contract/test_listing_budget.py` measures the
published surface with `cl100k_base`:

| What | Measured | Ceiling |
| --- | --- | --- |
| The four discovery tools | 1,957 | 2,000 |
| The 17 workflow tools | 3,887 | 4,000 |
| Everything one `tools/list` returns | 5,300 | 6,000 |
| The largest single tool | 636 | 700 |

The workflow half got 1,632 tokens cheaper by declaring one thing once: all 17
return the same result envelope, and each was publishing an identical 96-token
`outputSchema` to say so. The shape is published once as a resource now
(`kamiwaza://shapes/workflow-result`), where `resources/read` is a separate
call and a host that never validates never pays for it. The four discovery
tools still declare their own, because theirs differ — for comparison, Neon
publishes none across 113 tools and GitHub none across 45.

A host that wants the whole catalog anyway — one running its own code mode — asks
for it deliberately on `GET /mcp?codemode=false`, narrowable by `category` and
`q`, and the answer states its own measured token cost (`server/catalog.py`).
It is never the default, and it is behind the same admission as everything else.

`detail` decides how much of each entry comes back, which is a different
question from which entries come back:

| `detail` | Each entry carries | 336 operations |
| --- | --- | --- |
| `names` | identifier | 2,639 |
| `brief` | identifier, category, description | 8,672 |
| `full` (default) | every field | 22,533 |

### What a result tells you

Five failure kinds, each with a distinct next step, produced in one place
(`envelope/outcomes.py`). Two kinds sharing a next step fails at import, because
two kinds an agent cannot tell apart are one kind.

| Outcome | Next step | Retry the identical call? |
| --- | --- | --- |
| success | continue | — |
| `rejected_input` | `correct_and_retry`, naming the argument that did not validate | yes |
| `entitlement_refusal` | `stop_and_report`, naming what would grant it | **no** |
| `unmet_prerequisite` | `satisfy_prerequisite`, naming what was absent | yes |
| `expired_wait` | `resume_existing`, naming the work already under way | **no** — a retry creates a second one |
| `platform_fault` | `retry_only_if_idempotent`, naming the layer that failed | only if idempotent |

Every tool carries the protocol's advisory annotations — `readOnlyHint`,
`destructiveHint`, `idempotentHint`, `openWorldHint` — derived from the
operation's own effect rather than from an HTTP verb. Hints are advisory;
enforcement is server-side, and a host that ignores every hint is still refused.

### Resources and prompts

The knowledge resource `kamiwaza://docs/using-this-surface` carries the same six
topics as one Markdown document, assembled by `surface/docs.py` `as_document` and
committed at [`docs/using-this-surface.md`](docs/using-this-surface.md).
`tests/contract/test_resources.py` asserts the committed copy matches what the
server serves, and its failure message carries the regeneration command. Tool
descriptions state only what a tool does and returns, so behavioural rules live
in exactly one place.

The prompt primitive is **served and empty**. Served, because an unserved method
reads to a host as a gap in the server; empty, because prompts would become a
second home for behavioural policy. No completion capability is advertised, since
completion completes the arguments of a prompt or a resource template and this
server publishes neither.

## Operating it

- `GET /healthz` — liveness, shallow on purpose: a probe that consulted the
  platform would have an orchestrator restart a healthy process during someone
  else's outage.
- `GET /readyz` — readiness, reported separately from liveness, and flipped when
  the protocol transport is actually running rather than when the object graph
  exists.
- `GET /version` — this server's version, the pinned descriptor version and the
  served revisions, each read from the running install rather than from a
  constant, so a replica left behind by a partial rollout reports the old
  version. The same two versions are readable through the `docs` tool.

Shutdown drains in-flight work before terminating. One replica is fully
functional alone, and a second needs no leader election, sticky routing or
inter-instance messaging: the transport is stateless and task state is the
platform's.

Blocking SDK calls, workflows, and task-status reads run in worker threads, so
an in-flight platform request does not prevent `/healthz` from responding. The
SDK exposes no per-call timeout; shutting down still waits for accepted work.

## Installing it as a standalone server

```bash
pip install kamiwaza-mcp        # or run it directly: uvx kamiwaza-mcp
```

`kamiwaza-sdk` is pinned exactly, because this server's whole surface is
derived from its `kamiwaza_sdk.agent_tools` layer; both it and
`kamiwaza-extensions-lib` resolve from PyPI. `tests/contract/test_exact_pin.py`
fails if the pin becomes a range or the lock resolves the descriptor package
from anywhere but the index.

### Packages

Two standalone packages are built and checked on every change:

- **`kamiwaza-mcp` on PyPI**, the distribution this repository builds
  (`make package`).
- **`@kamiwaza/mcp` on npm** (`npm/`), a dependency-free launcher for clients
  that start servers with `npx`. It runs the `kamiwaza-mcp` release of its own
  version with `uvx`, or the container image when only Docker is available:
  `npx -y @kamiwaza/mcp`.

`.github/workflows/release-packages.yml` publishes both, with trusted
publishing, for a `vX.Y.Z` tag on `main` once `scripts/check_publishable.py`
passes and the `PUBLISH_PACKAGES` repository variable is `true`. CI runs the
same check on every change, so a dependency that only resolves from a private
source fails the change that adds it rather than the release. The repository
is internal, and npm does not generate provenance for a package published
from a non-public repository.

## Installing it as a Kamiwaza extension

The same server runs as a platform extension, built to the platform's own
`kz-ext` contract rather than a packaging scheme invented here: `kamiwaza.json`
(type `tool`), `docker-compose.yml`, and a `Dockerfile` that builds non-root
and runs with a read-only root filesystem. `kz-ext validate` passes.

`kz-ext dev` writes local deployment state under `.kz-ext/`. That directory is
excluded from Git and the Docker build context. The image build installs every
dependency from the lockfile with hashes, from the public index, so it needs no
credential.

```bash
kz-ext validate                          # the platform's own three validators
kz-ext dev                               # build, push, install into a cluster
kz-ext status                            # the installed instance and its phase
```

The extension is the **same** server: its entry point, `python -m
kamiwaza_mcp`, goes through the one application factory and selects the hosted
topology, because an extension runs behind the platform's edge and receives
exactly the forwarded context that topology reads. The install asks for
nothing. It prefers `KAMIWAZA_API_URL`; otherwise it derives the API root from
platform-injected `KAMIWAZA_INTERNAL_ORIGIN`, `KAMIWAZA_PUBLIC_API_URL`,
`KAMIWAZA_ORIGIN`, or the origin of `KAMIWAZA_APP_URL`. It uses
`KAMIWAZA_PLATFORM_GATEWAY_URL` only as the last fallback because an internal
gateway hostname might not match the platform certificate. No hostname, port,
container engine, or registry address is compiled into this choice. An
extension given no platform fact fails its rollout rather than starting against
the wrong cluster.

### Three deliberate deviations from the scaffolded template

Each was measured against a live cluster, and each is a place where the
`kz-ext` `tool` template disagrees with what the platform accepts or with what
this server can serve.

**The transport.** The template's `src/server.py` imports
`mcp.server.fastmcp.FastMCP` and runs `transport="sse"`. `FastMCP` does not
exist in the protocol library this server pins, and HTTP-with-SSE is deprecated
in both revisions it serves. The extension serves Streamable HTTP at `/mcp`.

**The probe.** Following from that, the platform's payload builder gives a
primary `tool` an `httpGet` probe on `/sse` — an endpoint this server does not
have, so the pod would never report ready. The descriptor package documents the
escape hatch for exactly this case, and `kamiwaza.json` uses it: a
`services.tool.healthCheck` override probing `/healthz`.

**The verification switch.** The template declares `KAMIWAZA_VERIFY_SSL`. With
it present the platform refuses the install outright — *"egress verification is
not weakenable by tenant intent, extension artifact content, a model requester,
a carried pod template, or workload environment"*. The platform is right, and
the variable is absent here: whether egress certificates are verified is the
platform's decision, not a value an extension carries.

### Two things to know before installing

Use the container engine and registry selected by local `kz-ext`
configuration; this repository does not require a specific engine, registry
implementation, hostname, or port.

The target may require immutable image references. `kz-ext dev` must resolve
those references through its configured build and registry workflow. If the
installed SDK sends tag-only images or fields the target rejects, stop and use
a compatible SDK instead of hand-authoring a deployment payload.

The platform **merges** a re-installed extension's service environment rather
than replacing it, so a payload corrected after a failed install can still
carry the field that failed. Delete the extension and install again rather
than reinstalling over it.

## Pointing an LLM client at it

Three ways to reach the same tool surface, and the configuration each takes.
The key name differs between clients — `mcpServers` here is the spelling Claude
Desktop, Cursor and VS Code use; `claude mcp add` and Codex write the same
fields under their own key.

**Standalone over stdio**, where the client launches the process. Nothing
listens on a port, and the credential never leaves the client's own config:

```json
{
  "mcpServers": {
    "kamiwaza": {
      "command": "kamiwaza-mcp",
      "env": {
        "KAMIWAZA_API_URL": "https://kamiwaza.example.com/api",
        "KAMIWAZA_MCP_CREDENTIAL": "<a credential that cluster issued>"
      }
    }
  }
}
```

Both variables are required and neither has a default: the process refuses to
start rather than guess a cluster or serve nobody. The credential is read from
the environment and never from `argv`, where every process on the machine could
read it.

**Standalone over HTTP**, for a client that attaches to a running server. Start
it with `kamiwaza-mcp --transport http --port 8080`; it binds loopback only:

```json
{
  "mcpServers": {
    "kamiwaza": {
      "type": "http",
      "url": "http://127.0.0.1:8080/mcp",
      "headers": { "Authorization": "Bearer <a credential that cluster issued>" }
    }
  }
}
```

A client that implements RFC 9728 needs no `headers` block: it reads
`/.well-known/oauth-protected-resource/mcp`, which this server publishes
unauthenticated, and authorizes from there. A client that does not gets a 401
carrying the same pointer in `WWW-Authenticate`.

**As a Kamiwaza extension**, where the server runs in the cluster behind the
platform edge and the client is remote. The URL is the platform host, the
runtime prefix, and the instance name `kz-ext status` reports:

```json
{
  "mcpServers": {
    "kamiwaza": {
      "type": "http",
      "url": "https://kamiwaza.example.com/runtime/tools/tool-kamiwaza-mcp/mcp",
      "headers": { "Authorization": "Bearer <the member's access token>" }
    }
  }
}
```

The edge authenticates, not this server. Measured against a live install:
`Authorization: Bearer <member token>` initializes; `x-auth-token` alone and no
header at all are both `401 {"detail":"Not authenticated"}` from the edge,
before anything here is reached. Everything after that — which member, which
roles, which tenant — arrives as the forwarded context the hosted topology
reads, so nothing else belongs in the client's configuration.

One thing a client can trip over in every mode. The two revisions served are
`2026-07-28`, declared per request in `MCP-Protocol-Version`, and `2025-11-25`,
negotiated once in `initialize` — so a client that opens with `initialize` is
answered about the second alone. Measured against a running server, a client
pinned to `2025-06-18` gets:

```json
{"code": -32022, "message": "Unsupported protocol version",
 "data": {"supported": ["2025-11-25"], "requested": "2025-06-18"}}
```

`2026-07-28` is absent from that list because it is not negotiated there, not
because it is unavailable: the same server answers `tools/list` with all 21
tools over that revision, given the header and the `_meta` envelope it
requires. Either way the refusal is explicit rather than a silent downgrade.

## Development

```bash
uv sync                                  # install, including dev dependencies
.venv/bin/python -m pytest               # unit, contract, integration, conformance
.venv/bin/python -m pytest -m conformance # one marker at a time
.venv/bin/python -m ruff check .
.venv/bin/python -m mypy
.venv/bin/python -m uat.runner           # the declared acceptance criteria
.venv/bin/python -m uat.selfcheck        # verify the harness itself
```

The four pytest markers are `unit`, `contract`, `integration` and `conformance`
(`pyproject.toml`). `uat.runner` takes `--area`, `--criterion` and `--json`; a
declared criterion with no registered case reports `NOT_EXERCISED` rather than
being skipped, so missing coverage is visible in the report instead of absent
from it.

This repository is developed with [spec-kit](https://github.com/github/spec-kit),
and the specification is the source of truth:

| Artifact | Purpose |
| --- | --- |
| [`spec.md`](specs/001-mcp-server/spec.md) | What the server must do — requirements and success criteria |
| [`plan.md`](specs/001-mcp-server/plan.md) | Technical context and constitution gates |
| [`research.md`](specs/001-mcp-server/research.md) | Every design decision with its alternatives |
| [`data-model.md`](specs/001-mcp-server/data-model.md) | Entities and their relationships |
| [`contracts/`](specs/001-mcp-server/contracts/) | Tool surface, resource descriptors, result envelopes, protocol conformance |
| [`tasks.md`](specs/001-mcp-server/tasks.md) | Implementation tasks, each mirrored to a GitHub issue |
| [`.specify/memory/constitution.md`](.specify/memory/constitution.md) | The principles every change is checked against |

Changes to behaviour start in the specification, not in the code. See
[`AGENTS.md`](AGENTS.md) for the working rules.

## Compatibility

| | |
| --- | --- |
| MCP revisions | `2026-07-28` and `2025-11-25`, both from one process |
| Extension | `io.modelcontextprotocol/tasks`, optional |
| Transports | Streamable HTTP, stdio |
| Primitives | tools, resources. Prompts served and empty |
| Python | `>=3.10` |
| Protocol library | `mcp>=2.2.0,<3.0.0` |
| Descriptor layer | `kamiwaza-sdk`, pinned exactly, readable from the surface |

## Security

- No caller credential is forwarded onward. The protocol names token passthrough
  an anti-pattern, and this server follows it.
- No secret appears in a tool description, a log line, or an error. A refusal
  repeats nothing the caller presented, so a probe is not logged verbatim.
- Identity and scope are never accepted from a request. A claim about the
  caller — `FORBIDDEN_CALLER_FIELDS` in `authority/admission.py` — is refused
  where a caller could be making it, at the top level of a call's arguments;
  the scope this server fills, `CALLER_SCOPE_FIELDS` (`workroom_id`,
  `tenant_id`), is refused at any depth, because it is stripped from every
  published shape. Both refuse before the platform is reached.
- Operations whose result is itself a credential are not published, and each
  withheld operation is refused by name with its reason rather than silently
  omitted.
- Every call is authorized individually. A prior discovery result is not
  authorization.

Report a suspected vulnerability privately to the Kamiwaza security contact
rather than in a public issue.

## License

Apache License 2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).
