npm package: @interweave-technologies/mcp-server
Description: MCP server for InterWeave SmartIntegration — lets AI agents manage integrations, flows, and QuickBooks data
Latest version: 0.1.0

# @interweave/mcp-server

Model Context Protocol (MCP) server for **InterWeave SmartIntegration**. Lets AI assistants (Claude Code, Cursor, Windsurf, and any MCP-compatible tool) manage integration flows, monitor system health, query QuickBooks Online data, and more — directly from a chat conversation.

---

## Quick Start

### Claude Code

Add to `.claude/settings.json` in your project root or `~/.claude/settings.json` globally:

```json
{
  "mcpServers": {
    "interweave": {
      "command": "npx",
      "args": ["@interweave/mcp-server"],
      "env": {
        "IW_BASE_URL": "https://interweave-ide.dev/iw-business-daemon",
        "IW_USER": "your-email@example.com",
        "IW_PASS": "your-password"
      }
    }
  }
}
```

### Cursor

Add to `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "interweave": {
      "command": "npx",
      "args": ["@interweave/mcp-server"],
      "env": {
        "IW_BASE_URL": "https://interweave-ide.dev/iw-business-daemon"
      }
    }
  }
}
```

### Windsurf

Add to `~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "interweave": {
      "command": "npx",
      "args": ["@interweave/mcp-server"],
      "env": {
        "IW_BASE_URL": "https://interweave-ide.dev/iw-business-daemon"
      }
    }
  }
}
```

---

## Configuration

| Environment variable | Required | Default                                    | Description                                           |
|----------------------|----------|--------------------------------------------|----------------------------------------------------|
| `IW_BASE_URL`        | No       | `http://localhost:9090/iw-business-daemon` | Base URL of the iw-business-daemon                 |
| `IW_USER`            | No       | —                                          | Email for authentication (use `interweave_login` if omitted) |
| `IW_PASS`            | No       | —                                          | Password for authentication (use `interweave_login` if omitted) |

If `IW_USER` and `IW_PASS` are not set, call the `interweave_login` tool first to authenticate. The token is then cached for the duration of the server process.

---

## Available Tools

| Tool                              | Description                                                        | Auth required |
|-----------------------------------|--------------------------------------------------------------------|---------------|
| `interweave_login`                | Authenticate and cache a Bearer token                              | No            |
| `interweave_get_health`           | System health: uptime, DB, memory, webapp status                   | No            |
| `interweave_list_flows`           | List all flows with state, schedule, and counters                  | Yes           |
| `interweave_start_flow`           | Start a flow by index (admin)                                      | Yes (admin)   |
| `interweave_stop_flow`            | Stop a flow by index (admin)                                       | Yes (admin)   |
| `interweave_get_dashboard`        | Real-time transaction summary, running jobs, recent activity       | Yes           |
| `interweave_get_connection_health`| Per-system connection status with live OAuth/endpoint checks       | Yes           |
| `interweave_get_metrics`          | Time-series metrics (executions, duration, records, payload)       | Yes           |
| `interweave_qbo_query`            | Read or write QuickBooks Online data via proxy                     | Yes           |
| `interweave_passthrough`          | Invoke a raw engine MCP tool (sync, validate, reconcile, export)   | Yes           |
| `interweave_create_auth_flow`     | Initialize engine profile / re-create flows for current user       | Yes (admin)   |

### Example prompts

```
"Check if InterWeave is healthy"
"List all my integration flows and show which ones are running"
"Start flow number 2"
"Show me the dashboard — how many transactions failed in the last 24 hours?"
"Query the QuickBooks Customer entity"
"Get connection health for all systems"
"Show me hourly metrics for the last 7 days"
```

---

## Local Development

```bash
# Build from source
cd C:/IW_Launcher/mcp-server
npm run build

# Run directly
node dist/index.js
```

Point the `command` in your MCP config to `node` and `args` to `["C:/IW_Launcher/mcp-server/dist/index.js"]` when testing locally.

---

## Protocol

- Transport: **stdio** (newline-delimited JSON-RPC 2.0)
- Protocol version: `2024-11-05`
- Capabilities: `{ tools: {} }`
- All errors are returned as MCP tool content with `isError: true` so clients surface them cleanly

---

## License

MIT — Copyright InterWeave SmartIntegration