> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ntropii.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Ntro MCP server

> Connect Claude.ai, Claude Desktop, Claude Code, and Microsoft Copilot Studio to Ntropii over the Model Context Protocol. The hosted test instance is at https://mcp.test.ntropii.com — no install required.

The Ntro MCP server exposes Ntropii Workspace as **tools** (write operations), **resources** (read-only data), and **prompts** (guided multi-step flows) for any Model Context Protocol client.

## Quick start — hosted test instance

The fastest way to try it is to point your MCP client at the hosted test instance:

```
https://mcp.test.ntropii.com
```

This is a managed deployment — no local install, no tunnels. Streamable HTTP transport. Currently runs without auth (test environment); production hosting with API-key auth lands when the platform leaves PoC. Treat it as throwaway: don't run anything you can't recreate.

### Wire it into your client

<Tabs>
  <Tab title="Claude.ai">
    **Settings → Connectors → Add custom connector**:

    | Field     | Value                           |
    | --------- | ------------------------------- |
    | Name      | `Ntropii (test)`                |
    | URL       | `https://mcp.test.ntropii.com`  |
    | Transport | Streamable HTTP (auto-detected) |

    The Ntropii tools appear in the tool picker once the connector saves.
  </Tab>

  <Tab title="Claude Code">
    Add it as an HTTP MCP server:

    ```bash theme={null}
    claude mcp add --transport http ntro https://mcp.test.ntropii.com
    ```

    Verify with `claude mcp list`. The tools show up under the `ntro_*` prefix in your next session.
  </Tab>

  <Tab title="Claude Desktop">
    Claude Desktop's stdio config can wrap a remote HTTP server with the `mcp-remote` bridge:

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

    ```json theme={null}
    {
      "mcpServers": {
        "ntro": {
          "command": "npx",
          "args": ["-y", "mcp-remote", "https://mcp.test.ntropii.com"]
        }
      }
    }
    ```

    Restart Claude Desktop.
  </Tab>

  <Tab title="Copilot Studio / other">
    Any MCP client that supports the Streamable HTTP transport can register the URL directly. See your client's MCP setup docs for the exact registration shape.
  </Tab>
</Tabs>

## What's included

| Type      | Examples                                                                                 |
| --------- | ---------------------------------------------------------------------------------------- |
| Tools     | `ntro_tenant_create`, `ntro_workflow_create`, `ntro_agent_create`, `ntro_task_next_step` |
| Resources | `ntro://tenants`, `ntro://tasks/{id}`, `ntro://schedule`                                 |
| Prompts   | `onboard_spv`, `run_nav`, `platform_status`                                              |

## Tools

Write operations — each tool accepts a structured payload, calls Ntropii Workspace, and returns the resulting object.

### Identity, tenants, entities

| Tool                                         | Purpose                                               |
| -------------------------------------------- | ----------------------------------------------------- |
| `ntro_whoami`                                | Get the current user identity and accessible tenants  |
| `ntro_tenant_create`                         | Create a tenant (client)                              |
| `ntro_tenant_list` / `_get` / `_deprovision` | Inspect / tear down tenants                           |
| `ntro_entity_create` / `_list`               | Create / list entities (SPVs / funds) within a tenant |

### Integrations (BYO data platforms)

| Tool                                          | Purpose                                                                                                                              |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `ntro_integration_create`                     | Register a customer-provided data platform config (Snowflake, Microsoft Fabric). BYO only — not needed for managed-postgres tenants. |
| `ntro_integration_test`                       | Test connectivity to a registered data platform                                                                                      |
| `ntro_integration_list` / `_get` / `_schemas` | Inspect registered platforms                                                                                                         |

### Runbooks (templates installed on the worker)

| Tool                     | Purpose                                                             |
| ------------------------ | ------------------------------------------------------------------- |
| `ntro_runbook_list`      | List runbooks registered with the worker                            |
| `ntro_runbook_get`       | Detail of one runbook, including the LLM-facing skill definition    |
| `ntro_runbook_templates` | Pull the full templates payload (`workflow.py`, `activities.py`, …) |
| `ntro_runbook_feedback`  | Submit feedback against a runbook, optionally tied to a task        |

### Workflows (runbook → entity bindings)

Per [N-80](https://linear.app/byng/issue/N-80), workflows are anchored to a `runbookSlug`. `ntro_workflow_create` takes `runbookSlug + entityId` and optionally a schedule — no separate deploy/push step.

| Tool                          | Purpose                                              |
| ----------------------------- | ---------------------------------------------------- |
| `ntro_workflow_create`        | Bind a runbook to an entity (with optional schedule) |
| `ntro_workflow_list` / `_get` | Inspect workflow bindings                            |
| `ntro_workflow_run`           | Trigger a workflow run — returns a task ID           |

### Agents (external)

| Tool                                   | Purpose                                                                                                                                                         |
| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ntro_agent_create`                    | Register a reference to an external Managed Agent (`anthropic://agents/<id>`, `copilot://agents/<id>`). Provisions a per-agent API key, returns plaintext once. |
| `ntro_agent_list` / `_get` / `_delete` | Inspect / delete agent registrations                                                                                                                            |
| `ntro_agent_create_version`            | Bump the agent's version snapshot (rolling out new prompts)                                                                                                     |

### Tasks (workflow executions)

| Tool                            | Purpose                                                               |
| ------------------------------- | --------------------------------------------------------------------- |
| `ntro_task_get`                 | Status + step progress for a task                                     |
| `ntro_task_next_step`           | Drive the loop: returns the next action the agent / human should take |
| `ntro_task_file_ingest`         | Submit a file to a task (signal a `submit_file` step)                 |
| `ntro_task_data_ingest`         | Submit structured data to a task                                      |
| `ntro_task_approve` / `_reject` | Resolve a review step                                                 |
| `ntro_task_logs`                | Tail task execution logs                                              |

### Schedules

| Tool                 | Purpose                     |
| -------------------- | --------------------------- |
| `ntro_schedule_list` | All scheduled / active runs |

## Resources

Read-only URIs — the MCP client fetches these by URI to populate context.

| URI                                | Description                         |
| ---------------------------------- | ----------------------------------- |
| `ntro://whoami`                    | Current user + workspace info       |
| `ntro://integrations`              | All data platform configs           |
| `ntro://integrations/{id}`         | Single data platform detail         |
| `ntro://integrations/{id}/schemas` | Schema discovery (warehouse layout) |
| `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 + step progress         |
| `ntro://schedule`                  | All tasks sorted by urgency         |

## Prompts

Guided multi-step flows. The agent receives a structured plan it works through, asking the human for input at key decision points.

| Prompt            | Description                                                                                      |
| ----------------- | ------------------------------------------------------------------------------------------------ |
| `onboard_spv`     | Walks through SPV setup: entity → COA → email integration → workflow registration → dry-run test |
| `run_nav`         | Monthly NAV execution with progress monitoring and exception handoffs                            |
| `platform_status` | Full platform overview — tenants, entities, workflows, active tasks                              |

## Self-host (advanced)

Run the MCP server locally if you need to point it at a private Ntropii Workspace, or want to develop against a forked tool surface.

### Install

<Tabs>
  <Tab title="pip (production)">
    ```bash theme={null}
    pip install ntro-mcp
    ntro-mcp --help
    ```
  </Tab>

  <Tab title="Editable (local dev)">
    ```bash theme={null}
    uv pip install -e ~/ntropii/ntro-python --python ~/.ntro-dev/bin/python
    uv pip install -e ~/ntropii/ntro-mcp     --python ~/.ntro-dev/bin/python

    ~/.ntro-dev/bin/ntro-mcp --help
    ```
  </Tab>
</Tabs>

### Configuration precedence

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 NAME` → named entry in `~/.ntro/config.toml`
4. `default_connection_name` in `~/.ntro/config.toml`

Run `ntro auth login` first ([API keys](/get-started/api-keys)) to seed the config file.

### Running locally

<Tabs>
  <Tab title="stdio (Claude Desktop / Claude Code)">
    The MCP client spawns `ntro-mcp` as a child process and talks over stdin/stdout. Zero networking required.

    ```json theme={null}
    {
      "mcpServers": {
        "ntro": {
          "command": "/home/you/.ntro-dev/bin/ntro-mcp",
          "args": ["--transport", "stdio", "--connection", "production"]
        }
      }
    }
    ```

    Or use explicit env vars instead of a connection name:

    ```json theme={null}
    {
      "mcpServers": {
        "ntro": {
          "command": "/home/you/.ntro-dev/bin/ntro-mcp",
          "args": ["--transport", "stdio"],
          "env": {
            "NTRO_HOST": "https://api.ntropii.com/v1",
            "NTRO_API_KEY": "ntro_prod_xxx"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="HTTP (claude.ai / other clients)">
    Run the server locally and tunnel it with `cloudflared` for clients that need an HTTPS URL:

    ```bash theme={null}
    # Terminal 1 — start the MCP server
    ntro-mcp --transport http --port 8000 --connection production

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

    For longer-term use, run on a server you control rather than relying on a development tunnel.
  </Tab>
</Tabs>

### CLI reference

```
ntro-mcp [OPTIONS]

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

## Related

<CardGroup cols={2}>
  <Card title="Coding agents overview" icon="robot" href="/tooling/coding-agents/overview">
    Why MCP matters for design-time runbook authoring.
  </Card>

  <Card title="Claude Code setup" icon="square-terminal" href="/tooling/coding-agents/claude-code">
    Wire the MCP server into Claude Code.
  </Card>

  <Card title="Copilot Studio setup" icon="microsoft" href="/tooling/coding-agents/copilot-studio">
    Wire the MCP server into Microsoft Copilot Studio.
  </Card>

  <Card title="Ntro CLI" icon="terminal" href="/tooling/ntro-cli">
    Same surface, exposed for humans in a terminal.
  </Card>
</CardGroup>