---
name: xeref
description: Manage the user's Xeref projects, tasks and notes over the Xeref MCP endpoint. Use when the user asks you to read, create, update or prioritize their Xeref work.
---

# Xeref

Xeref (https://xeref.ai) is an AI agent builder and productivity workspace. This skill lets you read and write the user's projects, tasks and notes through one HTTP endpoint that speaks MCP (JSON-RPC 2.0).

## Setup

1. The user copies their token from Xeref → Settings → MCP Server Token.
2. Keep it in the `XEREF_MCP_TOKEN` environment variable. Never hardcode it or print it back.

## Endpoint

`POST https://xeref.ai/api/mcp` with `Authorization: Bearer $XEREF_MCP_TOKEN` and a JSON-RPC 2.0 body. Supported methods: `initialize`, `tools/list`, `tools/call`.

```bash
curl -s https://xeref.ai/api/mcp \
  -H "Authorization: Bearer $XEREF_MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"create_task","arguments":{"title":"Ship pricing update","priority":"high"}}}'
```

For MCP clients (Claude Code, Cursor, VS Code, Antigravity):

```json
{
  "mcpServers": {
    "xeref": {
      "command": "npx",
      "args": ["mcp-remote", "https://xeref.ai/api/mcp", "--header", "Authorization: Bearer ${MCP_TOKEN}"],
      "env": { "MCP_TOKEN": "<your token>" }
    }
  }
}
```

## Tools

| Tool | What it does |
| --- | --- |
| `list_projects` | List all user projects |
| `create_project` | Create a new project |
| `delete_project` | Delete a project by id |
| `list_tasks` | List all user tasks |
| `create_task` | Create a new task |
| `update_task` | Update an existing task |
| `delete_task` | Delete a task by id |
| `list_notes` | List all user notes |
| `create_note` | Create a new note |
| `update_note` | Update an existing note |
| `delete_note` | Delete a note by id |
| `suggest_next_task` | Get top 3 priority-sorted todo tasks to work on next |

Call `tools/list` for the exact input schema of each tool.

## Limits

60 requests per minute per account. Over the limit the endpoint answers `429`.

## Tips for agents

- Call `tools/list` once before your first write.
- Resolve names to ids with the `list_*` tools; update and delete tools take ids.
- Use `suggest_next_task` when the user asks what to work on.
- Confirm with the user before running any `delete_*` tool.
- Batch reads where you can instead of looping.