MCP Server: Your AI Agent Just Learned to Book

Your AI agent can write an essay, analyze a contract, and translate documentation into 30 languages. But can it book a haircut appointment?

Until recently, the answer was no. Not because language models aren't smart enough. Because they had no standard way to communicate with external systems. Every integration required dedicated code, endpoint mapping, and manual authorization management.

Model Context Protocol (MCP) changes that. It's an open standard for communication between AI agents and external tools — something like USB-C for artificial intelligence. And the Timerise API has a built-in MCP server that lets agents perform real booking operations from the very first minute.

What Is Model Context Protocol?

MCP (Model Context Protocol) is a protocol developed by Anthropic that defines how AI agents can discover and use tools provided by external servers. Instead of hardcoding API calls in prompts, the agent connects to an MCP server and automatically learns what operations are available.

An analogy? Think of it as a restaurant menu. Instead of guessing what the kitchen can prepare, the agent gets a list of dishes (tools) with descriptions and ingredients (parameters). It picks what it needs and places an order.

In practice, it works like this:

The agent sends an initialize request to the MCP server.
The server returns a list of available tools with descriptions and parameter schemas.
The agent calls a specific tool with the appropriate arguments.
The server executes the operation and returns the result.

No glue code. No manual documentation. The agent understands what it can do on its own.

How Does the MCP Server Work in Timerise?

The MCP server is mounted directly on the Timerise API at the /mcp path. There's no separate process to run and no additional infrastructure to configure. All you need is an API key and the server address:

Sandbox: https://sandbox-api.timerise.io/mcp
Production: https://api.timerise.io/mcp

The authorization flow is straightforward:

The agent sends POST /mcp with an Authorization: Bearer <api-key> header.
The server creates a private MCP session and returns a session identifier in the mcp-session-id header.
Every subsequent call within that session uses the same API key.
The agent sends DELETE /mcp to end the session.

All Timerise access controls work as usual — the API key determines which projects and services the agent can access.

16 Tools for Complete Booking Management

The MCP server exposes 16 tools organized into four groups. They cover the entire booking lifecycle and give developers access to the API schema and key management.

Service Discovery

list_projects — list projects accessible with the given API key
get_project — details of a selected project
list_services — list services within a project
get_service — service details, including required form fields (formFields)
list_locations — list physical or virtual locations

Slot Availability

list_available_slots — query available slots within a given date range

Booking Management

create_booking — create a booking (slot-based or range-based)
confirm_booking — confirm a booking (change status from NEW to CONFIRMED)
cancel_booking — cancel a booking
reschedule_booking — move a booking to a different time
list_bookings — list bookings with filters (status, service, date range)
get_booking_details — full details of a specific booking

Developer Tools

get_api_schema — retrieve the full GraphQL API schema in SDL format, useful for exploring the data structure and building integrations
list_api_users — list API users and their keys within a project
create_api_key — create a new API key for a project (the key is shown only once)
delete_api_key — delete an API key by its ID

With these tools, an AI agent can not only handle bookings but also help developers with onboarding — fetch the API schema, create a sandbox key, and start integrating right away. All without leaving the IDE.

The agent doesn't need to know GraphQL structure or request formats. The MCP server abstracts those details and exposes clean, well-described tools.

From Question to Booking — Step by Step

Let's see how an AI agent handles the full booking process using MCP tools. The user writes: "Book me a haircut on Monday morning if anything is available."

Step 1: Find the project

The agent calls list_projects and receives a list of projects, e.g., "Haircut Studio" with ID prj_abc123.

Step 2: Find the service

The agent calls list_services with the projectId and finds "Men's Haircut" with ID svc_xyz789.

Step 3: Check required fields

The agent calls get_service to learn what data is needed for the booking. The server returns a field list: full name (required), email (required), phone (optional).

Step 4: Check availability

The agent calls list_available_slots with the Monday morning date range and receives a list of free slots with their IDs.

Step 5: Create the booking

The agent calls create_booking with the selected slot, user data, and timezone. The booking is created with status NEW.

Step 6: Confirm the booking

The agent calls confirm_booking to change the status to CONFIRMED.

Six tool calls. Zero lines of integration code. The agent determines the operation sequence on its own based on tool descriptions provided by the MCP server.

Setup in 2 Minutes

The Timerise MCP server works with any client that supports the MCP protocol. Here's how to connect it to popular tools.

Claude Desktop

Edit the config file (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "timerise": {
      "url": "https://sandbox-api.timerise.io/mcp",
      "headers": {
        "Authorization": "Bearer SANDBOX-your-api-key-here"
      }
    }
  }
}

Production: replace the URL with https://api.timerise.io/mcp and use a key with the PROD- prefix.

After restarting Claude Desktop, the hammer icon in the toolbar confirms that MCP tools are active. Ask Claude: "What Timerise projects can you see?" — it will automatically call list_projects.

Claude Code (CLI)

claude mcp add timerise \
  --transport http \
  --url https://sandbox-api.timerise.io/mcp \
  --header "Authorization: Bearer SANDBOX-your-api-key-here"

Cursor

Edit ~/.cursor/mcp.json or use Cursor Settings → MCP → Add Server:

{
  "mcpServers": {
    "timerise": {
      "url": "https://sandbox-api.timerise.io/mcp",
      "headers": {
        "Authorization": "Bearer SANDBOX-your-api-key-here"
      }
    }
  }
}

OpenAI Agents SDK (Python)

from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp

async with MCPServerStreamableHttp(
    url="https://sandbox-api.timerise.io/mcp",
    headers={"Authorization": "Bearer SANDBOX-your-api-key-here"},
) as timerise:
    agent = Agent(
        name="Booking Assistant",
        instructions="You help users book appointments.",
        mcp_servers=[timerise],
    )
    result = await Runner.run(
        agent, "Book me a slot for Monday morning."
    )

In every case, setup comes down to providing the MCP server URL and an API key. The protocol handles the rest.

Testing and Debugging Tools

Before releasing your agent to production, it's worth testing the MCP connection. Timerise gives you several paths to do that.

MCP Inspector

MCP Inspector is a browser-based tool for interactively testing MCP servers. Launch it with a single command:

npx @modelcontextprotocol/inspector

In the interface at http://localhost:5173, select Streamable HTTP as the transport, enter the address https://sandbox-api.timerise.io/mcp, and add the authorization header. You can browse all 16 tools, call them with any arguments, and observe raw JSON-RPC messages in the Network tab.

Testing with curl

If you prefer the terminal, initialize a session manually:

curl -si -X POST https://sandbox-api.timerise.io/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer SANDBOX-your-api-key-here" \
  -d '{
    "jsonrpc": "2.0",
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": { "name": "test", "version": "0.1" }
    },
    "id": 1
  }'

The server will return an mcp-session-id header. Use it in subsequent requests, e.g., to fetch the tool list (tools/list) or call a specific tool (tools/call).

Common Issues

404 Session not found — the session expired or the API was restarted. Send a new initialize request without the mcp-session-id header.
Not authorized — the API key doesn't have access to the given project. Check permissions in the Timerise dashboard.
Slot not available — the slot was booked by someone else. Call list_available_slots again.

MCP sessions live on the server side. If the connection is interrupted, the agent should reinitialize the session.

OAuth 2.1 for Claude.ai and Other Platforms

Beyond Bearer token authorization, Timerise supports OAuth 2.1 with PKCE — the standard required by Claude.ai, ChatGPT, Google Gemini, and other AI platforms connecting to remote MCP servers.

The process looks like this:

An administrator creates OAuth credentials via the GraphQL API (mcpOAuthClientCreate).
The clientId and clientSecret are configured in the AI platform's settings.
The platform automatically performs OAuth endpoint discovery, authorization, and token exchange.
The resulting access token is a standard Timerise API key.

This means an AI agent on Claude.ai can use the same 16 MCP tools as an agent connected via Bearer token — without additional configuration on the developer's side.

When Does MCP Make Sense?

The MCP server in Timerise works well in scenarios where an AI agent needs to autonomously perform booking operations without developer intervention:

Customer service chatbots — a bot on a website or WhatsApp that books, reschedules, or cancels appointments on its own.
Voice assistants — a voicebot in a clinic that suggests a new time to a patient during a phone call.
IDE agents — a developer in Cursor asks the agent to check available test slots in the sandbox environment.
Internal automation — a Python script with the OpenAI Agents SDK that checks daily occupancy and generates a report.

In each of these cases, the agent doesn't need dedicated integration code. An MCP server connection and an API key with the right permissions are enough.

Summary

Model Context Protocol is the missing link between intelligent language models and real business systems. Timerise embeds an MCP server directly in the API, eliminating the need to write integration code.

16 tools cover the full booking cycle — from service discovery, through availability checking, to creating and managing bookings. Setup takes minutes, not days. And with OAuth 2.1 support, the MCP server works both with local developer tools and cloud AI platforms.

If you're building an AI agent that needs to handle bookings, don't write another REST API wrapper. See how Timerise GraphQL API powers AI agents.

Timerise MCP Documentation →

Test the MCP Server with MCP Inspector →

<br>

Mateusz Sowa