npm package: @jetkey/mcp-bridge
Description: MCP bridge for multiplexing multiple Jetkey MCP servers into one stdio interface
Author: Jetkey
Latest version: 2.7.0

# @jetkey/mcp-bridge

MCP bridge that multiplexes multiple Jetkey cloud servers into a single stdio interface with 7 universal tools.

## Overview

The Jetkey MCP Bridge connects AI assistants to cloud infrastructure through the Model Context Protocol (MCP). It provides a unified interface to manage AWS, GCP, Azure, and other cloud services across multiple accounts—all through natural language.

**Key Benefits:**
- **Unified Access**: One bridge, multiple cloud accounts
- **Constant Tool Count**: 7 tools regardless of how many servers you have (50 servers = still 7 tools)
- **Natural Language Search**: Find cloud operations using semantic search
- **Safety Controls**: Dry-run previews and approval workflows for high-risk operations
- **Auto-Updates**: Background update checks with zero intervention

## Installation

### npm/npx

```bash
npx @jetkey/mcp-bridge YOUR_API_KEY
```

### MCP Client Configuration

Add to your MCP client's configuration file:

```json
{
  "mcpServers": {
    "jetkey": {
      "command": "npx",
      "args": ["-y", "@jetkey/mcp-bridge@latest", "YOUR_API_KEY"]
    }
  }
}
```

**Common config file locations:**
- **Cursor**: `~/.cursor/mcp.json`
- **Claude Desktop**: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows)
- **Other MCP clients**: Refer to client documentation

Get your API key from: https://jetkey.com/user/api-keys

## The 7 Universal Tools

### 1. `servers`
List all cloud MCP servers you have access to.

```typescript
servers()
// Returns: { servers: [{ id, name, slug, bundleName }], count }
```

### 2. `services`
List cloud services available in a specific server.

```typescript
services({ server_id: "df1e03e2-..." })
// Returns: { services: { aws: ["ec2", "s3", "lambda", ...] }, bundleName }
```

### 3. `operations`
List all operations for a service with pagination and filtering.

```typescript
operations({
  server_id: "df1e03e2-...",
  service: "s3",
  limit: 50,        // optional, default 50, max 200
  offset: 0,        // optional, for pagination
  tags: ["list"],   // optional, filter by operation type
  search: "bucket"  // optional, filter by name/description
})
// Returns: operation details including required parameters
```

### 4. `search`
Search for tools using natural language queries.

```typescript
search({
  query: "list S3 buckets",
  server_id: "df1e03e2-...",  // Required
  limit: 10,                   // optional
  threshold: 0.3               // optional, similarity threshold
})
// Returns: { tools: [{ toolId, name, description, similarity }] }
```

### 5. `inspect`
Get detailed parameter schemas and documentation for a tool.

```typescript
inspect({
  server_id: "df1e03e2-...",
  tool_id: "aws.s3.list-buckets",
  mode: "summary"  // or "full"
})
// Returns: { requiredParams, commonParams, examples, hint }
```

### 6. `execute`
Execute a cloud operation.

```typescript
execute({
  server_id: "df1e03e2-...",
  tool_id: "aws.s3.list-buckets",
  parameters: {},
  dryRun: true  // optional: preview without making changes
})
// Returns: operation result or dry-run preview
```

### 7. `approval`
Manage approval workflows for high-risk operations.

```typescript
// List pending approvals
approval({ action: "list" })

// Check specific approval status
approval({ action: "status", approval_id: "abc123" })

// Execute an approved operation
approval({ action: "retry", approval_id: "abc123" })
```

## Typical Workflow

```
1. "What cloud accounts do I have?"
   → servers()

2. "What services can I access in AWS Production?"
   → services({ server_id: "df1e03e2-..." })

3. "What S3 operations are available?"
   → operations({ server_id: "df1e03e2-...", service: "s3" })

4. "Find tools for listing buckets"
   → search({ query: "list S3 buckets", server_id: "df1e03e2-..." })

5. "What parameters does ListBuckets need?"
   → inspect({ server_id: "df1e03e2-...", tool_id: "aws.s3.list-buckets" })

6. "List my buckets"
   → execute({ server_id: "df1e03e2-...", tool_id: "aws.s3.list-buckets" })
```

## Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `JETKEY_MCP_URL` | Base URL for Jetkey API | `https://jetkey.com` |

Example for local development:

```json
{
  "mcpServers": {
    "jetkey": {
      "command": "npx",
      "args": ["-y", "@jetkey/mcp-bridge", "YOUR_API_KEY"],
      "env": {
        "JETKEY_MCP_URL": "http://localhost:3001"
      }
    }
  }
}
```

## Auto-Update Mechanism

The bridge automatically checks for updates on startup:
- Checks NPM registry (throttled to once per 24 hours)
- Downloads updates in the background (non-blocking)
- Updates apply on next bridge restart
- Gracefully handles network failures

Check your version:
```bash
npx @jetkey/mcp-bridge --version
```

## Architecture

```
MCP Client (Cursor, Claude Desktop, etc.)
    ↓ stdio
Jetkey MCP Bridge (7 universal tools)
    ↓ HTTP/JSON-RPC
Discovery API → [Server A, Server B, Server C, ...]
    ↓
Cloud Operations (AWS, GCP, Azure, etc.)
```

The bridge:
1. Discovers available servers via the Jetkey API
2. Exposes 7 universal tools that route to appropriate backends
3. Handles authentication, logging, and error handling

## Scalability

| Servers | Tools |
|---------|-------|
| 2 | 7 |
| 10 | 7 |
| 50 | 7 |
| 1000 | 7 |

Unlike per-server tool prefixing (which creates 4N tools for N servers), universal tools keep the interface constant.

## Development

```bash
# Install dependencies
npm install

# Build
npm run build

# Run locally
node dist/index.js YOUR_API_KEY
```

## Requirements

- Node.js >= 18.0.0
- Jetkey API key (from https://jetkey.com/user/api-keys)

## License

MIT

---

**Questions?** Visit [jetkey.com](https://jetkey.com) or email support@jetkey.com