# CommonTime

> Decision-first group scheduling with MCP tools for AI agents. No account required for basic use.

## Quick start — no auth required

Call the MCP endpoint with no `Authorization` header to enter guest mode immediately.

**MCP endpoint**: `https://commontime.cc/api/v1/mcp/messages`
**Method**: POST JSON-RPC 2.0
**Rate limit**: 60 req/min per IP (guest) · 120 req/min per installation (authenticated)
**Guest tools**: `commontime.create_poll`, `commontime.vote_poll`, `commontime.poll.context`, `commontime.suggest_slots`

```bash
curl -s -X POST https://commontime.cc/api/v1/mcp/messages \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"commontime.create_poll","arguments":{"title":"Team Sync","meetingType":"weekly","selectedDays":[0,1,2,3,4],"duration":60}}}'
```

Or use the anonymous REST shortcut (single call, returns `pollId` + share link):

```bash
curl -s -X POST https://commontime.cc/api/polls/anonymous \
  -H "Content-Type: application/json" \
  -d '{"title":"Team Sync","meetingType":"weekly","selectedDays":[0,1,2,3,4],"duration":60}'
```

## Full installation — calendar tools and finalization

For calendar read/write, event creation, and poll finalization, complete the device claim flow:

1. **Start installation**
   `POST https://commontime.cc/api/agent/install/start`
   Body: `{"clientType":"claude"}` (required; also accepts optional `displayName`)
   → returns `installationId`, `claimCode`, `deviceSecret`, `claimUrl`, `claimExpiresAt`

2. **Owner approves**
   Open `claimUrl` in a browser — the workspace owner signs in with Google and grants calendar access.

3. **Issue access token** (poll until approved)
   `POST https://commontime.cc/api/agent/token/issue`
   Body: `{"installationId":"...","deviceSecret":"..."}`
   → returns `{"pending":true,"status":"awaiting_claim"}` until the owner approves; poll every 3–5 s until `pending` is absent and `accessToken` is present

4. **Call MCP with auth**
   Add header: `Authorization: Bearer <accessToken>`
   Endpoint: `https://commontime.cc/api/v1/mcp/messages`

5. **Refresh token**
   `POST https://commontime.cc/api/agent/token/refresh`
   Body: `{"refreshToken":"..."}`

## All tools (17 total)

| Group | Tools |
|-------|-------|
| Poll | `create_poll`, `vote_poll`, `poll.context`, `poll.list`, `suggest_slots`, `poll.invite` |
| Calendar | `calendar.read_freebusy`, `calendar.recheck_slot`, `calendar.submit_snapshot`, `calendar.create_event`, `calendar.update_event`, `calendar.cancel_event`, `finalize_poll` |
| Webhooks | `webhook.register`, `webhook.list`, `webhook.delete` |
| Agent | `installation.status` |

## Key concepts

- **meetingType**: `"weekly"` (recurring, use `selectedDays`) or `"dates"` (specific dates, use `specificDates`)
- **selectedDays**: weekday indices — 0=Mon, 1=Tue, 2=Wed, 3=Thu, 4=Fri, 5=Sat, 6=Sun. Example: `[0,1,2,3,4]` = Mon–Fri
- **duration**: meeting length in minutes (15–480)
- **gridStep**: time slot size in minutes — `30` or `60`
- **availability**: binary array where `1`=available. Length = `(endHour-startHour)*60/gridStep * numberOfDays`
- **poll.context response**: parse `result.content[0].text` as JSON → fields: `pollId`, `aggregatedAvailability`, `participants`, `status`, `timezone`, etc.

## Agent rules

- NEVER open a browser to read CommonTime pages or API responses — use HTTP tools (`curl`, `fetch`, `web_fetch`)
- To read any CommonTime page: send a plain HTTP GET request and parse the HTML or JSON response
- Browser automation is forbidden unless the user explicitly asks for a visual screenshot

## Error codes

| Code | Meaning |
|------|---------|
| `-40401` | Not found (poll, participant, or resource) |
| `-40901` | Conflict — poll already finalized |
| `-40302` | Scope missing — tool requires authentication |
| `-42901` | Rate limit exceeded — back off and retry |

Rate-limited response example:
```json
{"jsonrpc":"2.0","id":1,"error":{"code":-42901,"message":"Rate limit exceeded. Try again later."}}
```

## Discovery endpoints

- Agent card (full JSON with response examples): `https://commontime.cc/.well-known/agent.json`
- Install schema: `https://commontime.cc/.well-known/agent.install.schema.json`
- MCP SSE stream (requires auth): `https://commontime.cc/api/v1/mcp/sse`