Metadata-Version: 2.4
Name: cnx-mcp
Version: 0.3.0
Summary: Local MCP stdio bridge for cnx — GPU rental negotiation agent (proxies to the live cnx /mcp HTTP endpoint). For paying, use cnx's standard x402 HTTP checkout with any x402-compliant wallet client (e.g. Coinbase's Agentic Wallet MCP)
License: MIT
Keywords: compute,gpu,mcp,negotiation,x402
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: mcp<2,>=1.28
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest-mock>=3.14; extra == 'dev'
Requires-Dist: pytest>=8.3.3; extra == 'dev'
Description-Content-Type: text/markdown

# cnx-mcp

A real, installable **local MCP stdio server** for [cnx](../README.md), the
GPU rental negotiation agent. It bridges any MCP-compatible host (Claude
Desktop, Claude Code, etc.) to the live cnx backend over stdio, so you can
add cnx to a host with one line instead of hand-rolling an HTTP bridge.

This package is a **thin protocol bridge, not a reimplementation**. On every
`tools/list` and `tools/call` request it forwards straight through to the
live cnx `/mcp` HTTP endpoint

```
https://ddlcl1en1j.execute-api.us-east-1.amazonaws.com/production/mcp
```

and reshapes the JSON-RPC response into the MCP types the SDK's stdio
transport expects. There are **no hardcoded tool schemas** in this package -
`list_tools()` always reflects whatever the live backend currently serves,
so this bridge can never drift out of sync with the real tool set.

## Install & run

Published on PyPI as `cnx-mcp`. Any of these work:

```bash
# No install - run directly
uvx cnx-mcp

# Same idea, via pipx
pipx run cnx-mcp

# Install then run
pip install cnx-mcp
cnx-mcp
```

Or from a local checkout of this repo instead:

```bash
# From the repo root
pip install -e ./mcp-server
cnx-mcp

# or, without a persistent install, via uv:
uvx --from ./mcp-server cnx-mcp
```

## Configuring an MCP host

Add cnx to your host's MCP server config. For Claude Desktop
(`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "cnx": {
      "command": "uvx",
      "args": ["cnx-mcp"]
    }
  }
}
```

Or, if you installed it with `pip install cnx-mcp`:

```json
{
  "mcpServers": {
    "cnx": {
      "command": "cnx-mcp"
    }
  }
}
```

Prefer a local checkout instead of the published package? Point a host there directly:

```json
{
  "mcpServers": {
    "cnx": {
      "command": "uvx",
      "args": ["--from", "/absolute/path/to/mcp-server", "cnx-mcp"]
    }
  }
}
```

Claude Code (`.mcp.json` or `claude mcp add`) uses the same
`command`/`args` shape.

## Pointing at a different backend

By default `cnx-mcp` talks to the live production endpoint. Override it with
`CNX_MCP_BASE_URL` - useful for local development or a staging deployment
without needing a new release of this package:

```json
{
  "mcpServers": {
    "cnx": {
      "command": "uvx",
      "args": ["cnx-mcp"],
      "env": {
        "CNX_MCP_BASE_URL": "https://your-staging-endpoint.example.com/mcp"
      }
    }
  }
}
```

Or from the shell:

```bash
CNX_MCP_BASE_URL=http://localhost:3000/mcp cnx-mcp
```

## Available tools

The tool list is discovered dynamically from the live backend on every
`tools/list` call - this README is not the source of truth for it, and this
package adds no tools of its own. As of this writing the backend serves 5
tools: `rent_compute`, `negotiate_price`, `submit_payment`,
`check_rental_status`, `report_unreachable`. See the main repo's
`SKILLS.md` for the current, authoritative description of each.

## Paying: use Coinbase's Agentic Wallet MCP (or any x402-compliant client)

Settling a real rental means signing an x402 EIP-3009 payment
authorization. `cnx-mcp` (this package) is deliberately **not** where that
happens - it does not hold a wallet, a keystore, or any signing logic at
all, on purpose.

cnx exposes a standard HTTP x402 checkout directly on the backend
(`POST /x402/quotes` → `POST /x402/checkout/{quote_id}` → `GET
/x402/rentals/{task_id}`; see the main repo's [TECHNICAL.md](../TECHNICAL.md)
§12). Any x402-compliant wallet client can drive that flow end to end -
**Coinbase's Agentic Wallet MCP** (`npx @coinbase/payments-mcp`) is the
recommended one: install it alongside `cnx-mcp`, log in once (embedded
wallet via email/OTP, no API key), fund it with test USDC, and set your own
per-call/per-session spend limits that the agent cannot raise or bypass.
From there, paying cnx is just another x402 checkout it already knows how
to complete - deployed and verified: a real quote → 402 challenge →
signed payload → on-chain settlement has round-tripped successfully
against production.

Any other x402-compliant client (`x402-fetch`, `x402-axios`, etc.) works
the same way - Coinbase's is simply a well-built, zero-key-management
example, not a requirement.

If you'd rather sign payments yourself from a bare terminal instead of via
a wallet client, see the main repo's `scripts/cnx_pay.py`.

> **Note:** earlier versions of this package (`<0.3.0`) shipped their own
> local signing broker (`pay_and_confirm`, an encrypted disposable
> keystore, `cnx-mcp init-wallet`). That was removed once cnx's x402 HTTP
> endpoint made a cnx-specific signer redundant - a generic x402 wallet
> client covers the identical need without this package also having to
> carry and audit its own crypto-signing code.

## Development

```bash
cd mcp-server
python3 -m venv .venv
.venv/bin/pip install -e '.[dev]'
.venv/bin/pytest tests/ -v
```

## Publishing

Releasing a new version is deliberate, not automatic on every commit.
`.github/workflows/publish-pypi.yml` builds, tests, and publishes to PyPI
when a `cnx-mcp-vX.Y.Z` tag is pushed - it first checks the tag matches
`pyproject.toml`'s `version`, so a mismatched tag fails loudly instead of
publishing the wrong thing. To release:

```bash
# after bumping version in pyproject.toml and committing
git tag cnx-mcp-v0.3.0
git push origin cnx-mcp-v0.3.0
```

Requires a `PYPI_API_TOKEN` repo secret (GitHub repo settings -> Secrets
and variables -> Actions), scoped to the `cnx-mcp` PyPI project - not yet
set as of this writing.
