The Beebole MCP Server: Connect Claude and ChatGPT

Beebole exposes an MCP server so your own AI assistant can log time, read timesheets, and list projects — with exactly your permissions. Connect hosted assistants such as Claude and ChatGPT in a couple of clicks, or point developer tools like Claude Code and Cursor at the same server with your API key. Every connection is listed under Connected apps, where you can disconnect it anytime.

An assistant connected to Beebole acts as you: it sees only the data your role allows, and its actions are recorded like your own. This page is about connecting external assistants to your data — Beebole’s built-in AI features are covered in Beebole AI.

What a connected assistant can do

The server exposes a set of tools grouped around the things people actually do in Beebole, always bounded by your permissions. The list below covers the main ones rather than every tool:

What you want to do	Tools the assistant uses
Understand your account first	`get_context` — who you are, how your organization names its structure (category names and the name of each level, custom fields and the items they belong to), and how its timesheet works: periodicity and current period, the project levels an entry needs, which plannings accept time, the lock date, the entry rules, and the approval workflow
Look things up	`list` (projects, tasks, tags, people, roles, time off types, expense types, work schedules, custom fields, categories), `list_sub_projects`, `get_attributes` and `export` for an item’s settings — including each inherited value and where it comes from
Track time	`record_time` (one entry or many), `update_time_record`, `copy_time_records` for “same as last week”, `delete_time_records`, plus `get_time_records` and `get_timesheet_days` for what is logged and what is missing day by day
Check time off	`get_absence_balance` — the balance per quota, including carry-forward, and the time off types you may book
Submit and approve	`get_timesheet_status`, `submit_timesheet`, `get_team_timesheets` and `send_timesheet_reminder` for the people you review, `list_pending_approvals`, `get_approval_digest`, `approve_timesheet`, `reject_timesheet`, `get_approval_history`
Propose entries instead of writing them	`push_suggestions`, `get_suggestions`, `accept_suggestions`, `dismiss_suggestions` — drafts you confirm yourself in the app, like Beebole’s own suggested entries
Handle expenses	`get_expense_records`, `record_expense`, `update_expense_record`, `delete_expense_records`
Get figures out	`get_reports` and `run_report` — a saved report, an exact report configuration, or a plain-language question — and `get_budget_status` for budget consumption, with the same per-person and per-project splits as the Budget Status report
Work with planning	`get_tasks` and `update_tasks` — what is planned, and changing dates, planned time, owner, or status
Set things up	`add`, `update_attributes`, `set_custom_field_value`, `assign` and `unassign` for links between items (project access, managers, tags, schedules, task owners), `get_rates`, `set_rate` and `delete_rate` for the dated billing and cost rate history, `invite_persons`, and `archive`, `unarchive` and `delete` for projects, tasks, tags, people, roles, time off types, expense types, work schedules, and custom fields
Manage work schedules	`set_schedule` — create a work schedule or rewrite an existing one: the repeating cycle of hours per day, with time pairs and work-from-home days, weekly or a rotating cycle of any length — then `assign` (relation `schedule_to_person`) to put a person on it from a date; `list` reads each schedule weekday by weekday
See who changed what	`get_audit_trail`, when your subscription includes the audit trail

So you can ask your assistant things like “log 2 hours on Website Redesign for today”, “what did I track this week?”, “how much of the Acme budget is left?”, “set up a 4-day week schedule and put Alice Martin on it from October 1”, or — if you’re an approver — “approve the timesheets waiting on me”. Each tool tells your assistant whether it only reads data or changes it, and which changes are destructive, so a well-behaved assistant asks before deleting anything. Everything runs through the same rules as the app: the lock date, entry restrictions, approval status, and your role all apply, and a refusal comes back to the assistant as the reason Beebole gives. For work schedules, set_schedule takes the whole cycle at once. For a weekly schedule, each weekday gets a number of hours, a list of time pairs such as 09:00 to 12:30 and 13:30 to 17:00, or both together with a work-from-home flag; a weekday left out is a non-working day. Every call replaces the full cycle rather than merging into it, so the assistant reads the current schedule with list first and sends it back complete with the change. It passes schedule_id to rewrite an existing schedule (and a name to rename it at the same time) or a name alone to create one, and describes a rotating roster that is not a week by listing its days in cycle order with cycle_days. A new schedule has nobody on it until the assistant assigns people to it from a start date — the same rules as in Work schedules. Deleting is for undoing a batch that was just created. Beebole refuses to delete anything still in use — a project, task, or person with time entries, an expense type with expense entries, a time off type with allowances, a custom field that already holds values, or a role or work schedule people are still assigned to — and the assistant receives the reason together with the suggestion to archive instead. Archiving keeps the item’s history in reports but takes it out of timesheets and of every picker, and unarchive brings it back.

Find your server URL and API key

Everything you need is on the Assistant page — click Assistant in the sidebar:

Server URL — the address of your Beebole MCP server, with a Copy button.
API key — click Show my API key to reveal it, then Copy. Only needed for developer tools; hosted connectors sign in instead.

Connect your AI tools section of the Beebole Assistant page: steps to add Beebole as a custom connector in claude.ai or ChatGPT with the Server URL and its Copy button, then the Show my API key button and the Claude Code command and Cursor or Claude Desktop JSON snippets, each with Copy — The Connect your AI tools section of the Assistant page

Connect a hosted assistant (claude.ai, ChatGPT)

Copy the server URL

On the Assistant page, copy the Server URL.

Add it as a custom connector

In claude.ai or ChatGPT, add the URL as a custom connector.

You are asked to sign in to Beebole and authorize the access — no API key needed. This is a standard OAuth 2.1 sign-in, so the assistant never sees your credentials and receives an access token it has to refresh. Once authorized, the assistant appears under Connected apps.

Connect a developer tool

Claude Code
Cursor / Claude Desktop

Run this command, replacing YOUR_API_KEY with your API key and the URL with your Server URL:

claude mcp add --transport http beebole https://your-server/mcp --header "apikey: YOUR_API_KEY"

Add this block to the tool’s MCP configuration (JSON), replacing the URL and key with yours:

{
  "mcpServers": {
    "beebole": {
      "url": "https://your-server/mcp",
      "headers": { "apikey": "YOUR_API_KEY" }
    }
  }
}

Your API key gives full access to your Beebole account with your permissions. Keep it out of shared configuration and repositories. If a key leaks, click Reset on the Assistant page — the old key stops working immediately.

Review and disconnect connections

Assistants you authorized through sign-in appear on the Assistant page under Connected apps, with the app’s name and when it was connected. Click Disconnect to revoke a connection — the assistant loses access immediately and must be authorized again to reconnect. Tools connected with your API key are not listed there; they stop working when you Reset the key.

Beebole AI

Beebole’s built-in AI: suggested entries, report builder, and approval review.

Beebole API

Query and mutate your Beebole data programmatically with GraphQL.

Roles & permissions

What your role allows — and therefore what a connected assistant can do as you.

Webhooks

Push Beebole events to external systems in real time.

Frequently asked questions

Which AI assistants work with Beebole?

Any assistant that supports the MCP standard. Hosted assistants like claude.ai and ChatGPT connect through a custom connector with a sign-in flow, while developer tools like Claude Code, Claude Desktop, and Cursor connect with your Beebole API key.

What data can a connected assistant access?

Exactly what you can. The connection carries your permissions, so the assistant sees the projects, tasks, and timesheets your role allows — nothing more. It records time on your own timesheet by default, and on someone else’s only where your role already lets you do that; it can act on approvals only if you are an approver. There is no separate permission layer for the assistant: Beebole refuses whatever you could not do yourself, and the assistant gets the refusal.

How do I revoke an assistant's access to Beebole?

For hosted assistants, click Disconnect next to the app under Connected apps on the Assistant page. For tools connected with your API key, click Reset next to the key — every tool using the old key loses access immediately.

Do I need an API key to connect claude.ai or ChatGPT?

No. Hosted connectors use a sign-in flow: add Beebole’s server URL as a custom connector, sign in, and authorize the access. The API key is only for developer tools that can’t open a sign-in window.

Can a connected assistant delete things in my Beebole account?

Only what your role allows, and only what is not in use. The delete tool is flagged as destructive, so a well-behaved assistant asks before using it, and Beebole refuses to delete a project, task, person, role, time off type, expense type, work schedule, or custom field that still has time entries, expense entries, allowances, custom field values, or people assigned to it. The refusal reaches the assistant with the reason and the suggestion to archive instead, which keeps the history in reports and is reversible with unarchive.

GraphQL API

Examples

MCP & Webhooks

Legacy

MCP server: connect Claude, ChatGPT, and more

What a connected assistant can do

Find your server URL and API key

Connect a hosted assistant (claude.ai, ChatGPT)

Connect a developer tool

Review and disconnect connections

Beebole AI

Beebole API

Roles & permissions

Webhooks

Frequently asked questions

​What a connected assistant can do

​Find your server URL and API key

​Connect a hosted assistant (claude.ai, ChatGPT)

​Connect a developer tool

​Review and disconnect connections

​Related content

Beebole AI

Beebole API

Roles & permissions

Webhooks

​Frequently asked questions

What a connected assistant can do

Find your server URL and API key

Connect a hosted assistant (claude.ai, ChatGPT)

Connect a developer tool

Review and disconnect connections

Related content

Frequently asked questions