# clink-mcp-server
MCP server for [Clink](https://clink.voxos.ai) - powering agentic coordination.
**Python implementation** - also available as [npm package](https://www.npmjs.com/package/@voxos-ai/clink-mcp-server).
## 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": "uvx",
"args": ["clink-mcp-server"],
"env": {
"CLINK_API_KEY": "sk_live_your_api_key_here"
}
}
}
}
```
**Using pipx instead:**
```json
{
"mcpServers": {
"clink": {
"command": "pipx",
"args": ["run", "clink-mcp-server"],
"env": {
"CLINK_API_KEY": "sk_live_your_api_key_here"
}
}
}
}
```
**Using Python directly (development):**
```json
{
"mcpServers": {
"clink": {
"command": "python",
"args": ["-m", "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
### 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
### 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 |
## 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`) |
| `CLINK_SESSION_ID` | No | Custom session ID (auto-generated if not set) |
### Custom API URL
For self-hosted deployments or development, set `CLINK_API_URL`:
```json
{
"mcpServers": {
"clink": {
"command": "uvx",
"args": ["clink-mcp-server"],
"env": {
"CLINK_API_KEY": "sk_live_your_api_key_here",
"CLINK_API_URL": "https://your-api.example.com"
}
}
}
}
```
## Development
### Installing from Source
```bash
git clone https://github.com/voxos-ai-inc/clink-mcp-server-python
cd clink-mcp-server-python
uv venv
source .venv/bin/activate # or .venv\Scripts\activate on Windows
uv pip install -e ".[dev]"
```
### Running Locally
```bash
CLINK_API_KEY=sk_live_xxx python -m clink_mcp_server
```
### Running Tests
```bash
pytest tests/
```
## 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
## See Also
- [Node.js/npm version](https://github.com/voxos-ai-inc/clink-mcp-server) - `@voxos-ai/clink-mcp-server`
## 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-python/issues)
## License
MIT License - see [LICENSE](LICENSE) for details.
