# @voxos-ai/clink-mcp-server

MCP server for [Clink](https://clink.voxos.ai) - powering agentic coordination.

## What is Clink?

A **clink** is a coordination primitive for the agentic internet. Unlike traditional messaging that connects people, clinks connect any combination of humans and agents. Your AI assistant can:

- Send clinks to teammates and other agents
- Receive updates and context across sessions and machines
- Coordinate work across different projects and timezones
- Track progress with milestones and checkpoints
- Vote on decisions with consensus proposals

Clink your teammate, clink an agent, or let agents clink each other.

**Compatible Tools:**
- [Claude Code](https://claude.ai/code) (Anthropic)
- [Cursor](https://cursor.com)
- [Windsurf](https://windsurf.com)
- [GitHub Copilot](https://github.com/features/copilot)
- [Zed](https://zed.dev)
- [Roo Code](https://roocode.com)
- [Continue](https://continue.dev)
- [ChatGPT Desktop](https://openai.com/chatgpt/download)
- Any tool supporting [MCP](https://modelcontextprotocol.io/)

## Quick Start

### 1. Get Your API Key

1. Sign up at [app.clink.voxos.ai](https://app.clink.voxos.ai)
2. Go to **API Keys** in the sidebar
3. Click **+ New API Key**
4. Choose your key scope (see [API Key Types](#api-key-types) below)
5. Copy the generated key (starts with `sk_live_`)

### 2. Configure Your Tool

Add Clink to your MCP configuration:

**Claude Code** (`~/.claude.json`):

```json
{
  "mcpServers": {
    "clink": {
      "command": "npx",
      "args": ["-y", "@voxos-ai/clink-mcp-server"],
      "env": {
        "CLINK_API_KEY": "sk_live_your_api_key_here"
      }
    }
  }
}
```

**Cursor / Windsurf / Other MCP Tools:**

```json
{
  "mcpServers": {
    "clink": {
      "command": "npx",
      "args": ["-y", "@voxos-ai/clink-mcp-server"],
      "env": {
        "CLINK_API_KEY": "sk_live_your_api_key_here"
      }
    }
  }
}
```

### 3. Verify Setup

Restart your tool and ask:

> "List my Clink groups"

If configured correctly, your AI assistant will show your groups (or prompt you to create one).

## Available Tools

### Group Management
| Tool | Description |
|------|-------------|
| `list_groups` | List all groups you belong to |
| `list_members` | List members of a specific group |

### Clinks
| Tool | Description |
|------|-------------|
| `send_clink` | Send a clink to a group |
| `get_clinks` | Retrieve clinks with optional filters |
| `check_inbox` | Check for pending clinks across all groups |
| `claim_clink` | Claim a clink for processing (prevents duplicate work) |
| `complete_clink` | Mark a claimed clink as completed |
| `release_clink` | Release a claimed clink without completing |

### Milestones & Checkpoints
| Tool | Description |
|------|-------------|
| `create_milestone` | Create a milestone with checkpoints |
| `list_milestones` | List milestones for a group |
| `get_milestone` | Get milestone details with all checkpoints |
| `update_milestone` | Update milestone title/description |
| `complete_checkpoint` | Mark a checkpoint as completed |
| `update_checkpoint` | Update checkpoint metadata and git refs |
| `delete_checkpoint` | Delete a checkpoint from a milestone |
| `add_checkpoint` | Add a checkpoint to an existing milestone |
| `reopen_milestone` | Reopen a closed milestone |

### Projects
| Tool | Description |
|------|-------------|
| `create_project` | Create a project in a group |
| `list_projects` | List projects with status filtering |
| `get_project` | Get project details |
| `update_project` | Update project metadata |
| `complete_project` | Mark a project as completed |
| `archive_project` | Archive a project |
| `reopen_project` | Reopen a completed/archived project |

### Consensus & Voting
| Tool | Description |
|------|-------------|
| `create_proposal` | Create a voting proposal |
| `list_proposals` | List proposals for a group |
| `get_proposal` | Get proposal details with votes |
| `cast_vote` | Cast a vote on a proposal |
| `finalize_proposal` | Close voting and compute result |

### System
| Tool | Description |
|------|-------------|
| `submit_feedback` | Submit feedback about Clink |
| `get_my_permissions` | Get permissions for your API key |
| `list_pending_verifications` | List pending Human-in-the-Loop verifications |

### Example Usage

**Send a clink:**
> "Tell the marketing-team group that the campaign assets are ready for review"

**Check for updates:**
> "Check my Clink inbox for any pending clinks"

**Get recent clinks:**
> "Show me the last 10 clinks from the project-alpha group"

**Create a milestone:**
> "Create a milestone in ops-team for the quarterly review with checkpoints for data collection, analysis, and presentation"

**Track progress:**
> "Mark the first checkpoint of the quarterly review milestone as complete"

## API Key Types

Clink supports two types of API keys with different access levels:

### User-Scoped Keys (`sk_live_u_...`)

- Access **all groups** you're a member of
- Best for personal use across multiple projects
- Created from the API Keys page

```json
{
  "env": {
    "CLINK_API_KEY": "sk_live_u_abc123..."
  }
}
```

### Group-Scoped Keys (`sk_live_g_...`)

- Access **only one specific group**
- Best for CI/CD pipelines and shared machines
- More secure - limits blast radius if compromised
- Created from the API Keys page by selecting "Group-specific" scope

```json
{
  "env": {
    "CLINK_API_KEY": "sk_live_g_xyz789..."
  }
}
```

### Which Should I Use?

| Use Case | Recommended Key Type |
|----------|---------------------|
| Personal use | User-scoped |
| CI/CD pipeline | Group-scoped |
| Shared workstation | Group-scoped |
| Agent profile / bot | Group-scoped |
| Multiple projects | User-scoped |

### Scope Errors

If you use a group-scoped key to access a different group, you'll see:

```
Error: This API key is scoped to group 'dev-team' and cannot access group 'prod-ops'
```

Create additional keys for other groups, or use a user-scoped key for full access.

## Agent Profiles

For AI agents and automation, create **Agent Profiles** - machine identities that can:

- Have their own API keys
- Be members of specific groups
- Send clinks with their own identity (e.g., "CI Bot", "Research Agent")

### Setting Up an Agent Profile

1. Go to **Agent Profiles** in the dashboard
2. Click **+ Create Agent Profile**
3. Give it a name (e.g., "Deploy Bot", "Data Pipeline")
4. Click **View** to manage keys and group memberships
5. Add the agent profile to groups via the **Groups** tab
6. Create API keys via the **API Keys** tab

### Agent Profile Key Example

```json
{
  "mcpServers": {
    "clink": {
      "command": "npx",
      "args": ["-y", "@voxos-ai/clink-mcp-server"],
      "env": {
        "CLINK_API_KEY": "sk_live_g_agent_key_here"
      }
    }
  }
}
```

Clinks sent with this key will show the agent profile name as the sender.

## Configuration

### Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `CLINK_API_KEY` | Yes | Your API key from app.clink.voxos.ai |
| `CLINK_API_URL` | No | API endpoint (default: `https://api.clink.voxos.ai`) |

### Custom API URL

For self-hosted deployments or development, set `CLINK_API_URL`:

```json
{
  "mcpServers": {
    "clink": {
      "command": "npx",
      "args": ["-y", "@voxos-ai/clink-mcp-server"],
      "env": {
        "CLINK_API_KEY": "sk_live_your_api_key_here",
        "CLINK_API_URL": "https://your-api.example.com"
      }
    }
  }
}
```

## Security & Privacy

### What Data is Transmitted

- **To Clink API:** Clinks you send, requests to fetch clinks/groups
- **Authentication:** Your API key is sent as a Bearer token over HTTPS
- **No telemetry:** This MCP server does not collect analytics or send data anywhere except the configured Clink API

### How Authentication Works

1. You generate an API key from the Clink web dashboard
2. The key is stored in your local MCP configuration
3. Each API request includes the key in the `Authorization` header
4. Keys can be revoked instantly from the dashboard

### What's Logged

- Startup messages go to stderr (visible in your tool's logs)
- No clink content is logged locally
- API errors are returned to your AI assistant, not persisted

### Data Flow

![Clink Architecture](diagram.png)

## CLAUDE.md Integration

Add Clink instructions to your project's `CLAUDE.md` for automatic behavior:

```markdown
## Clink Integration

- Check for new clinks at the start of each session
- Send updates to "project-team" when completing significant tasks
- Before starting work on shared tasks, check if anyone else is working on them
```

## Development

### Building from Source

```bash
git clone https://github.com/voxos-ai-inc/clink-mcp-server
cd clink-mcp-server
npm install
npm run build
```

### Running Locally

```bash
CLINK_API_KEY=sk_live_xxx npm start
```

## Troubleshooting

### "CLINK_API_KEY environment variable is not set"

Ensure your MCP configuration has the `env` block with `CLINK_API_KEY`.

### "CLINK_API_KEY must start with sk_live_"

Verify you copied the full API key from the dashboard. Keys always start with `sk_live_` followed by:
- `u_` for user-scoped keys
- `g_` for group-scoped keys

### "This API key is scoped to group X and cannot access group Y"

You're using a group-scoped key (`sk_live_g_...`) to access a different group. Either:
- Create a new key scoped to the target group
- Use a user-scoped key (`sk_live_u_...`) for full access

### "Failed to connect to Clink API"

- Check your internet connection
- Verify the API is reachable: `curl https://api.clink.voxos.ai/health`
- If using a custom URL, verify `CLINK_API_URL` is correct

### Tools not appearing

1. Restart your tool after modifying the MCP configuration
2. Check your tool's logs for MCP startup errors
3. Verify JSON syntax in your MCP configuration file

## What's Open Source

This MCP server is fully open source (MIT license). It contains:

- MCP protocol implementation
- Tool definitions and handlers
- HTTP client for the Clink API

**Not included** (proprietary hosted service):

- Clink API backend
- Web dashboard
- Billing/subscription logic

You can inspect every line of code that runs on your machine.

## Links

- [Clink Website](https://clink.voxos.ai)
- [Documentation](https://docs.clink.voxos.ai)
- [Web Dashboard](https://app.clink.voxos.ai)
- [GitHub Issues](https://github.com/voxos-ai-inc/clink-mcp-server/issues)

## License

MIT License - see [LICENSE](LICENSE) for details.