Metadata-Version: 2.4
Name: sesame-mcp
Version: 0.1.2
Summary: MCP server exposing the Sesame human-in-the-loop approval API as an agent tool
Project-URL: Homepage, https://github.com/lavanpuri1999/sesame
Project-URL: Repository, https://github.com/lavanpuri1999/sesame
Project-URL: Issues, https://github.com/lavanpuri1999/sesame/issues
Author: Sesame
License: MIT
License-File: LICENSE
Keywords: agent,approval,human-in-the-loop,mcp,model-context-protocol,sesame
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: httpx>=0.27
Requires-Dist: mcp>=1.2
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# sesame-mcp

An [MCP](https://modelcontextprotocol.io) server that exposes Sesame's
human-in-the-loop approval API as an agent tool. Drop it into any MCP-capable
agent (Claude Desktop, Claude Code, Cursor, etc.) and that agent gains an
approval gate it can call **before** doing anything destructive or sensitive —
with **zero integration code** on your side.

The server talks only to Sesame's public REST contract over stdio. It does not
import the broker, core, or CLI packages.

## Tool

```
request_approval(
    action: str,
    summary: str,
    reason: str | None = None,
    timeout_seconds: int = 300,
) -> dict
```

It triggers an approval (`POST /v1/approvals`), then long-polls
(`GET /v1/approvals/{id}?wait=true`) until a human decides or `timeout_seconds`
elapses. A human is notified via Telegram + push and must approve or deny.

Returns:

```jsonc
{ "approval_id": "ap_...", "status": "approved" | "denied" | "expired" | "timeout" | "error", "decided": true }
```

The agent must only proceed with the action when `status == "approved"`.

## Configuration

Set **`SESAME_API_KEY`** — create one in the
[Sesame dashboard](https://getsesame.dev/api-keys) (**API Keys**). That's the
only thing required; the server reaches the hosted Sesame broker automatically
and fails fast at startup if the key is missing.

Self-hosting only: point `SESAME_BROKER_URL` at your own broker (defaults to
`https://getsesame.dev`).

## Install

```bash
uv pip install sesame-mcp        # or: pip install sesame-mcp
sesame-mcp                       # runs the stdio server
```

## Register in an MCP client

### Claude Code

```bash
claude mcp add sesame \
  --env SESAME_API_KEY=sk_live_xxx \
  -- uvx sesame-mcp
```

`SESAME_API_KEY` is the only required env var — the server targets the hosted
broker by default. Add `--env SESAME_BROKER_URL=...` only to self-host or hit a
local broker.

`uvx sesame-mcp` downloads and runs the published package on demand — no prior
install needed.

### Claude Desktop / generic JSON config

Add to your client's `mcpServers` block (e.g. `claude_desktop_config.json`):

```jsonc
{
  "mcpServers": {
    "sesame": {
      "command": "sesame-mcp",
      "env": {
        "SESAME_API_KEY": "sk_live_xxx"
      }
    }
  }
}
```

If `sesame-mcp` is not on the client's `PATH`, use `uvx`:

```jsonc
{
  "mcpServers": {
    "sesame": {
      "command": "uvx",
      "args": ["sesame-mcp"],
      "env": { "SESAME_API_KEY": "sk_live_xxx" }
    }
  }
}
```

Any MCP-capable agent that loads this server gets the approval gate
automatically — no SDK calls, no glue code.

## Development

```bash
uv run --extra dev ruff check .
uv run --extra dev pytest tests/
```
