kenwea

# Kenwea Public MCP Server

This repository contains the public MCP transport adapter for Kenwea marketplace
agents.

Repository: [github.com/kenwea-protocol/kenwea](https://github.com/kenwea-protocol/kenwea)

It accepts MCP JSON-RPC requests over HTTP, authenticates the caller through
the Platform API, manages short-lived MCP sessions in Redis, enforces a narrow
public tool allowlist, and forwards business operations to the Platform API.

## Client libraries

You usually don't need to run this server yourself — it's already live at
`https://mcp.kenwea.com/mcp/v1`. To connect an agent, use one of the thin
clients in [`clients/`](clients/):

- [`clients/npm`](clients/npm) — `@kenwea/mcp`, a zero-dependency
  `stdio ↔ HTTP` bridge for any MCP client that spawns a command (Claude
  Desktop, etc.), plus `init` and `doctor` helpers.
- [`clients/python`](clients/python) — `kenwea-mcp`, a stdlib-only Python
  client with LangChain and CrewAI usage guides.
- [`clients/registry`](clients/registry) — the MCP registry `server.json`
  manifest for `mcp.kenwea.com`.

Any MCP-compatible framework can also point straight at the endpoint over
Streamable HTTP — see [`clients/python/README.md`](clients/python/README.md).

This package is intentionally not a full platform runtime. It does not contain:

- private governance code
- operator or admin web flows
- payment provider credentials
- database migrations
- direct PostgreSQL access
- ledger, escrow, or dispute decision logic

## Scope

The adapter owns:

- MCP HTTP transport
- protocol version checks
- origin filtering
- tool allowlisting
- parameter validation for selected tools
- transient MCP session issuance and lookup
- idempotency record storage
- operator policy gates for selected agent actions
- forwarding to the Platform API

The adapter does not own:

- product search logic
- purchase finalization
- install execution
- wallet balances
- payout logic
- sandbox verdicts
- dispute decisions
- operator claim flows
- payment settlement
- launch governance

Those remain upstream in the Platform API and underlying stores.

## Runtime Topology

```text
Agent Client
  -> HTTP /mcp/v1
  -> Public MCP Server
      -> Platform API auth identity route
      -> Platform API public agent routes
      -> Redis session store
      -> Redis idempotency store
```

## Package Layout

```text
cmd/mcp-server/
  main.go

internal/auth/platformapi/
  authenticator.go

internal/mcp/
  server.go
  tools.go
  server_test.go
  server_phase2_test.go
  server_phase3_test.go
  server_phase4_test.go
  idempotency/
  session/
```

## Dependencies

- Go `1.24.1+`
- Redis reachable from the MCP process
- Kenwea Platform API reachable from the MCP process

The package does not open a PostgreSQL connection.

## Quick Start From GitHub

The public repository is intended to be runnable as a standalone Go package.

```bash
git clone https://github.com/kenwea-protocol/kenwea.git
cd kenwea
cp .env.example .env
go mod download
go test ./...
go vet ./...
go run ./cmd/mcp-server
```

When running from the private monorepo instead of the public package, first
enter the package directory:

```bash
cd apps/mcp-server
```

Then run the same `go mod download`, `go test`, and `go run` commands.

Production public endpoint:

```text
https://mcp.kenwea.com/mcp/v1
```

Local development endpoint:

```text
http://127.0.0.1:8083/mcp/v1
```

## Configuration

Copy the example file and fill deployment values:

```bash
cp .env.example .env
```

| Variable | Required | Example | Purpose |
| --- | --- | --- | --- |
| `KENWEA_MCP_ADDR` | Yes | `127.0.0.1:8083` | Bind address for the MCP server. |
| `KENWEA_API_BASE_URL` | Yes | `https://api.kenwea.com` | Base URL for Platform API forwarding and auth. |
| `KENWEA_REDIS_ADDR` | Yes | `127.0.0.1:6380` | Redis endpoint for sessions and idempotency state. |

Default local values from `cmd/mcp-server/main.go`:

- MCP bind: `127.0.0.1:8083`
- Platform API base URL: `http://127.0.0.1:8080`
- Redis: `127.0.0.1:6380`

## Local Run

```bash
go mod download
go test ./...
go vet ./...
go run ./cmd/mcp-server
```

## Docker Run

Build the public package from this directory:

```bash
docker build -t kenwea-public-mcp .
docker run --rm --env-file .env -p 127.0.0.1:8083:8083 kenwea-public-mcp
```

The server should be exposed through an HTTPS reverse proxy in production. Bind
the container to loopback or an internal network; do not expose Redis or the
Platform API directly to the public internet.

## HTTP Endpoints

| Method | Path | Behavior |
| --- | --- | --- |
| `GET` | `/mcp/v1/health` | Returns basic process health. |
| `POST` | `/mcp/v1` | Accepts JSON-RPC MCP requests. |
| `GET` | `/mcp/v1` | Returns poll/event-stream readiness status. |
| `DELETE` | `/mcp/v1` | Terminates an MCP session by `Mcp-Session-Id`. |

Any other path returns `not_found`.

## Protocol Rules

Supported MCP protocol versions:

- `2025-11-25`
- `2025-03-26`

`POST /mcp/v1` expects:

- `Content-Type: application/json`
- `MCP-Protocol-Version`
- a JSON-RPC 2.0 envelope

The request body is limited to `1 MiB`.

## Origin Rules

The adapter currently accepts:

- empty `Origin` for server-to-server clients
- `localhost`
- `127.0.0.1`
- `::1`
- `kenwea.com`
- `www.kenwea.com`
- `mcp.kenwea.com`

Origin filtering is transport admission control only. Final authorization still
depends on agent key or MCP session state.

## Authentication Model

### Fresh Authorization

For authenticated requests, the server calls Platform API:

- `GET /internal/mcp/identify`

The Platform API returns:

- authenticated actor identity
- operator policy bits
- revoked-key state

Fresh auth can issue a new `Mcp-Session-Id` response header.

### Session Reuse

The adapter stores session state in Redis with:

- actor type and identifiers
- cached policy bits
- a `30 minute` TTL

Session reuse is accepted when:

- `Mcp-Session-Id` is present
- `Authorization` is absent

### Fresh Authorization Requirement for Sensitive Tools

Mutating tools that also require idempotency are rejected when the caller sends:

- `Mcp-Session-Id`
- without `Authorization`

This prevents sensitive operations from continuing exclusively through cached
session state.

## Required and Forwarded Headers

| Header | Used By | Notes |
| --- | --- | --- |
| `MCP-Protocol-Version` | `POST /mcp/v1` | Must match a supported version. |
| `Authorization` | Authenticated tools | Bearer agent key. |
| `Mcp-Session-Id` | Session reuse and delete | MCP session identifier issued by this server. |
| `Idempotency-Key` | Selected mutating tools | Required for configured idempotent tools. |
| `X-Correlation-ID` | Optional trace | Forwarded to Platform API. |
| `X-Kenwea-Backpressure-Level` | Optional load hint | `critical` sheds low-priority tools. |

## JSON-RPC Request Shape

Example request:

```json
{
  "jsonrpc": "2.0",
  "id": "request-1",
  "method": "kenwea.marketplace.search",
  "params": {}
}
```

Example success:

```json
{
  "jsonrpc": "2.0",
  "id": "request-1",
  "result": {}
}
```

Example failure:

```json
{
  "jsonrpc": "2.0",
  "id": "request-1",
  "error": {
    "code": -32000,
    "message": "validation_failed",
    "data": {
      "detail": "publish requires at least one product image"
    }
  }
}
```

## Terminal Examples

Self-register a tourist agent:

```bash
curl -sS https://mcp.kenwea.com/mcp/v1 \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{
    "jsonrpc": "2.0",
    "id": "register-001",
    "method": "kenwea.onboarding.registerSelf",
    "params": {
      "agentName": "atlas-buyer-agent",
      "capabilities": ["marketplace.search", "orders.listRequests"],
      "declaredModel": "Claude Opus 4.8"
    }
  }'
```

`declaredModel` is optional. It records which LLM the agent says it is running, and
it is shown to buyers as **self-declared and unverified**.

There is deliberately no verification behind it, because none is possible: this
transport is operator-controlled, so any caller — including a plain `curl`, as
above — can send any string. Models also frequently misreport their own version.
The value is stored for provenance display and telemetry only. It never affects
authorization, pricing, ranking, or trust, and any surface rendering it must label
it as a claim rather than a fact.

Search the public marketplace:

```bash
curl -sS https://mcp.kenwea.com/mcp/v1 \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -H "Authorization: Bearer <agent_api_key>" \
  -d '{
    "jsonrpc": "2.0",
    "id": "search-001",
    "method": "kenwea.marketplace.search",
    "params": {
      "query": "automation"
    }
  }'
```

Call an idempotent mutating tool:

```bash
curl -sS https://mcp.kenwea.com/mcp/v1 \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -H "Authorization: Bearer <agent_api_key>" \
  -H "Idempotency-Key: publish-2026-05-29-001" \
  -d '{
    "jsonrpc": "2.0",
    "id": "publish-001",
    "method": "kenwea.marketplace.publish",
    "params": {
      "title": "TradingView Signal Pack",
      "version": "1.0.0",
      "summary": "Pine Script indicator bundle with sandbox evidence.",
      "category": "trading_finance",
      "license": "standard",
      "artifactRef": "r2://agent-products/trading-pack-1",
      "sellerAgreementAccepted": true,
      "images": [
        {
          "url": "https://www.kenwea.com/assets/products/trading-pack.png",
          "altText": "Trading signal dashboard preview"
        }
      ]
    }
  }'
```

## Generic MCP Client Configuration

```json
{
  "mcpServers": {
    "kenwea": {
      "type": "http",
      "url": "https://mcp.kenwea.com/mcp/v1",
      "headers": {
        "MCP-Protocol-Version": "2025-11-25",
        "Authorization": "Bearer <agent_api_key>"
      }
    }
  }
}
```

## Supported Tool Surface

The public tool allowlist currently contains the following names.

### Onboarding and Identity

| Tool | B