# ntro-mcp

MCP (Model Context Protocol) server for the [ntro platform](https://ntropii.com). Exposes the Workspace API as tools, resources, and prompts that Claude can call directly — from Claude Desktop, Claude Code, or claude.ai.

---

## What's included

| Type | Count | Examples |
|---|---|---|
| Tools | 8 | `ntro_whoami`, `ntro_tenant_create`, `ntro_workflow_run` |
| Resources | 11 | `ntro://tenants`, `ntro://tasks/{id}`, `ntro://schedule` |
| Prompts | 3 | `onboard_spv`, `run_nav`, `platform_status` |

---

## Installation

### Prerequisites

- Python 3.11+
- The `ntro` SDK installed (see ntro-python)
- The Workspace API running locally or a valid `~/.ntro/config.toml`

### Development install (local workspace)

```bash
# Create a shared venv (once — skip if already done)
uv venv ~/.ntro-dev --python 3.12

# Install the SDK (editable)
uv pip install -e ~/ntropii/ntro-python --python ~/.ntro-dev/bin/python

# Install ntro-mcp (editable)
uv pip install -e ~/ntropii/ntro-mcp --python ~/.ntro-dev/bin/python
```

Verify:

```bash
~/.ntro-dev/bin/ntro-mcp --help
```

### Production install (once published to PyPI)

```bash
pip install ntro-mcp
```

---

## Configuration

The server resolves the API connection in this priority order:

1. `--ntro-host` / `--ntro-api-key` CLI flags
2. `NTRO_HOST` / `NTRO_API_KEY` environment variables
3. `--connection` flag → named entry in `~/.ntro/config.toml`
4. `default_connection_name` in `~/.ntro/config.toml`

Example `~/.ntro/config.toml`:

```toml
default_connection_name = "local"

[connections.local]
host = "http://localhost:3000/v1"
api_key = "ntro_dev_key"

[connections.production]
host = "https://api.ntropii.com/v1"
api_key = "your-api-key-here"
```

Run `ntro auth login` (from `ntro-cli`) to create this file interactively.

---

## Claude Desktop setup (stdio)

This is the recommended transport for local use. Claude Desktop spawns `ntro-mcp` as a child process and communicates over stdin/stdout.

**1. Find your Claude Desktop config file:**

| OS | Path |
|---|---|
| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
| Windows (WSL) | `/mnt/c/Users/<Username>/AppData/Roaming/Claude/claude_desktop_config.json` |

**2. Add the ntro server:**

```json
{
  "mcpServers": {
    "ntro": {
      "command": "/home/ollie/.ntro-dev/bin/ntro-mcp",
      "args": ["--transport", "stdio", "--connection", "local"],
      "env": {}
    }
  }
}
```

Or use explicit env vars instead of a connection name:

```json
{
  "mcpServers": {
    "ntro": {
      "command": "/home/ollie/.ntro-dev/bin/ntro-mcp",
      "args": ["--transport", "stdio"],
      "env": {
        "NTRO_HOST": "http://localhost:3000/v1",
        "NTRO_API_KEY": "ntro_dev_key"
      }
    }
  }
}
```

**3. Restart Claude Desktop.** The ntro tools will appear in the tool picker.

---

## Claude Code setup (stdio)

Add to your project's `.claude/mcp.json` or the global `~/.claude/mcp.json`:

```json
{
  "mcpServers": {
    "ntro": {
      "command": "/home/ollie/.ntro-dev/bin/ntro-mcp",
      "args": ["--transport", "stdio", "--connection", "local"]
    }
  }
}
```

---

## claude.ai setup (Streamable HTTP)

For use with claude.ai, the server must be reachable over HTTPS. Run it locally and tunnel with cloudflared:

```bash
# Terminal 1 — start the MCP server
ntro-mcp --transport http --port 8000 --connection local

# Terminal 2 — expose it over HTTPS
cloudflared tunnel --url http://localhost:8000
# → https://random-words.trycloudflare.com
```

Then in Claude.ai: **Settings → Connected Apps → Add MCP Server** → paste the tunnel URL.

---

## CLI reference

```
ntro-mcp [OPTIONS]

Options:
  --transport {http,stdio}    Transport type (default: stdio)
  --port INT                  HTTP port (default: 8000)
  --host TEXT                 HTTP bind host (default: 127.0.0.1)
  -c, --connection TEXT       Connection name from ~/.ntro/config.toml
  --ntro-host TEXT            Workspace API URL (overrides config)
  --ntro-api-key TEXT         API key (overrides config)
```

Examples:

```bash
# Local dev via config file
ntro-mcp --transport stdio --connection local

# Explicit target (no config file needed)
ntro-mcp --transport stdio --ntro-host http://localhost:3000/v1 --ntro-api-key ntro_dev_key

# HTTP server for tunnelling to claude.ai
ntro-mcp --transport http --port 8000 --connection local

# Production
ntro-mcp --transport stdio --connection production
```

---

## Tool reference

### Write tools

| Tool | Description |
|---|---|
| `ntro_whoami` | Get current user identity |
| `ntro_integration_create` | Register a data platform (Databricks, Snowflake) |
| `ntro_integration_test` | Test connectivity to a data platform |
| `ntro_tenant_create` | Create a new tenant (client cell) |
| `ntro_entity_create` | Create an SPV/fund within a tenant |
| `ntro_workflow_create` | Register a workflow definition |
| `ntro_workflow_deploy` | Deploy a workflow version to a tenant cell |
| `ntro_workflow_run` | Trigger a workflow run — returns a task ID |

### Resources

| URI | Description |
|---|---|
| `ntro://whoami` | Current user and workspace info |
| `ntro://integrations` | All data platform configs |
| `ntro://integrations/{id}` | Single data platform detail |
| `ntro://integrations/{id}/schemas` | Schema discovery (Databricks tables) |
| `ntro://tenants` | All tenants |
| `ntro://tenants/{slug}` | Single tenant detail |
| `ntro://entities` | All entities across tenants |
| `ntro://workflows` | All workflow definitions |
| `ntro://workflows/{id}` | Workflow detail |
| `ntro://tasks/{id}` | Task status and step progress |
| `ntro://schedule` | All tasks sorted by urgency |

### Prompts

| Prompt | Description |
|---|---|
| `onboard_spv` | Guided SPV setup: entity → COA → email → workflow → dry-run test |
| `run_nav` | Guided monthly NAV execution with progress monitoring |
| `platform_status` | Full platform overview — tenants, entities, workflows, active tasks |

---

## Related packages

| Package | Description |
|---|---|
| `ntro` | Python SDK (dependency of this package) |
| `ntro-cli` | CLI tool — `ntro tenant list`, `ntro workflow run`, etc. |
