Guide

MCP server

The Model Context Protocol (MCP) is an open standard that lets AI assistants call tools in external systems. Kelomo ships an MCP server, so an assistant can answer questions like "who is working today", "how much leave do I have left" or "is the payroll material ready" directly from your organisation's data.

How it works

The server speaks stateless Streamable HTTP at https://api.kelomo.fi/mcp and authenticates with the same bearer API keys as the REST API. It is deliberately a thin client of the public API: every tool call travels through the same HTTP surface as any integration, so capability scopes, feature gates, rate limits and the audit trail apply structurally — an assistant can never see more than the key it carries. A connection without a key still lists the tool catalogue; tool calls then answer with instructions for minting one.

• Read-first tool set. A curated catalogue of about forty tools covers presence and schedules (who_is_working, get_schedule, team_absence, my_shifts), timesheets and balances (my_week, my_open_days, get_timesheet, leave_balance, balance_history), your own drafts and requests (my_requests, my_tasks), the approvals inbox, payroll readiness, sales and invoicing figures (sales_pipeline, list_quotes, list_invoices, customer_360), project status, tenant catalogues (list_catalogs), credential introspection (my_access) and report generation.
• Writes that stop at a draft. log_time records the caller's own hours with project allocation, create_trip and create_expense file a travel claim, request_absence asks for leave, claim_open_shift asks for a shift, and create_task, create_lead, log_activity and create_intake create work someone triages. The claim-shaped ones are two-phase — the first call previews, nothing is saved until you call again with confirm=true — and every write lands in a state a person still has to act on, carries an idempotency key (an ambiguous network failure cannot double-file a claim) and answers with a link to the exact Kelomo page where the person finishes the job.
• Two tools that decide. approve and reject settle an approvals-inbox item, so both require reading the queue first and cannot be undone from the assistant — and reject refuses to run without a stated reason, because a rejection nobody explained is bad management.
• Workflow prompts and resources. The server also publishes five workflow prompts (weekly review, approvals triage, payroll close, travel claim from a description, sales morning briefing) that hosts surface as slash commands, and resources such as kelomo://me/week; a large generated report is returned as a resource link rather than pasted into the conversation.
• Deliberately absent: punching the clock (an assistant cannot witness "I am at work now", and the person tapping is already there) and issuing or dispatching invoices (money documents with unbroken numbering).
• Scope with the key. The key's capabilities decide what the tools can reach; a read-only key with narrow scopes is the right default for assistant use.

Connect from Claude Code

claude mcp add --transport http kelomo https://api.kelomo.fi/mcp \
  --header "Authorization: Bearer kelomo_YOUR_KEY"

Then ask in a session: "Using kelomo, who is working today?" Claude Code discovers the tools automatically.

Connect from Cursor

Add the server to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "kelomo": {
      "url": "https://api.kelomo.fi/mcp",
      "headers": {
        "Authorization": "Bearer kelomo_YOUR_KEY"
      }
    }
  }
}

Connect from the Claude API

Applications built on the Claude API can pass the server in the mcp_servers parameter — Claude then calls Kelomo tools itself during the conversation:

{
  "model": "claude-sonnet-4-5",
  "max_tokens": 1024,
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://api.kelomo.fi/mcp",
      "name": "kelomo",
      "authorization_token": "kelomo_YOUR_KEY"
    }
  ],
  "messages": [
    { "role": "user", "content": "Who is working today, and are there coverage gaps this week?" }
  ]
}

Which clients this covers

API-key connections cover Claude Code, Cursor, the Claude API and other agents where you control the configuration.