# Platoona MCP Server

An MCP (Model Context Protocol) server that connects AI assistants like Claude Code, Cursor, and others to **10,000+ SaaS integrations** through Platoona Connect.

## Features

- **search-tools** - Semantic search (RAG) for 10K+ integration actions
- **list-integrations** - Browse available integrations
- **list-connections** - View your active connections
- **connect-app** - Connect to integrations (OAuth or API key)
- **execute-tool** - Execute integration actions
- **disconnect-app** - Disconnect from integrations

## Prerequisites

1. A Platoona Connect account
2. Your Platoona API key (get it from [Platoona Connect Portal](https://app.platoona.com/connect))
3. Node.js 18+

## Installation

### Option 1: Install from npm (recommended)

```bash
npm install -g @platoona/mcp
```

### Option 2: Install from source

```bash
git clone https://github.com/platoona/platoona-mcp.git
cd platoona-mcp
npm install
npm run build
```

## Configuration

### Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `PLATOONA_API_KEY` | Yes | Your Platoona Connect API key |
| `PLATOONA_BASE_URL` | No | Custom API URL (for self-hosted) |

**Note:** User ID is automatically derived from your API key using a deterministic hash. This ensures consistent identification across sessions - same API key always produces the same user ID (`mcp_<hash>`).

## Usage with Claude Code

Add to your Claude Code configuration (`~/.claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "platoona": {
      "command": "npx",
      "args": ["@platoona/mcp"],
      "env": {
        "PLATOONA_API_KEY": "platoona_xxx..."
      }
    }
  }
}
```

Or if installed globally:

```json
{
  "mcpServers": {
    "platoona": {
      "command": "platoona-mcp",
      "env": {
        "PLATOONA_API_KEY": "platoona_xxx..."
      }
    }
  }
}
```

## Usage with Cursor

Add to your Cursor MCP settings:

```json
{
  "mcpServers": {
    "platoona": {
      "command": "npx",
      "args": ["@platoona/mcp"],
      "env": {
        "PLATOONA_API_KEY": "platoona_xxx..."
      }
    }
  }
}
```

## Available Tools

### search-tools

Search for integration tools using semantic/RAG search.

```
Input:
- query: "send a message to slack"
- integrationFilter: "slack" (optional)
- limit: 10 (optional)

Output:
- List of matching tools with IDs, descriptions, and similarity scores
```

### list-integrations

List available integrations that can be connected.

```
Input:
- search: "email" (optional)
- limit: 20 (optional)

Output:
- List of integrations with IDs, names, and slugs
```

### list-connections

List all active connections for your MCP user.

```
Input: (none required)

Output:
- List of connections with IDs, status, and expiration
```

### connect-app

Connect to an integration.

```
Input:
- integration: "slack" or UUID
- apiKey: "..." (for API key integrations)
- scopes: ["read", "write"] (for OAuth)

Output:
- For API key: connectionId and status
- For OAuth: authUrl to complete authorization
```

### execute-tool

Execute an integration action.

```
Input:
- action: "slack:send-message" or UUID
- parameters: { channel: "#general", text: "Hello!" }
- timeout: 30000 (optional)

Output:
- Execution result with output data
```

### disconnect-app

Disconnect from an integration.

```
Input:
- integration: "slack" or UUID

Output:
- Success confirmation
```

## Example Workflow

1. **Search for tools:**
   ```
   "Search for tools to send a Slack message"
   ```

2. **Check connections:**
   ```
   "List my Slack connections"
   ```

3. **Connect if needed:**
   ```
   "Connect to Slack" (will return OAuth URL)
   ```

4. **Execute the tool:**
   ```
   "Send a Slack message to #general saying Hello!"
   ```

## API Endpoints Used

This MCP uses the dedicated `/mcp/*` endpoints for simplified integration:

| Endpoint | Purpose |
|----------|---------|
| `POST /mcp/tools/search` | RAG search for integration tools |
| `POST /mcp/connect` | Connect to integration (OAuth or API key) |
| `POST /mcp/execute` | Execute an integration action |
| `GET /mcp/connections` | List active connections |
| `POST /mcp/disconnect` | Disconnect from integration |
| `GET /ipaas/integrations` | List available integrations |

## Development

```bash
# Install dependencies
bun install

# Run in development mode
bun run dev

# Build for production
bun run build

# Start production server
bun start
```

## License

MIT

## Support

- [Platoona Documentation](https://docs.platoona.com)
- [GitHub Issues](https://github.com/platoona/platoona-mcp/issues)