Rize MCP Server

For agents and integrations

Your Rize workspace, available to any AI assistant that speaks MCP

The Rize MCP server exposes your tracked time, clients, projects, tasks, keywords, contracts, profitability data, Skills, Agent Context, report runs, and routine runs to Claude, ChatGPT, Cursor, and anything else built on the Model Context Protocol. It is a thin translation layer over the same public GraphQL API the Rize apps use, so an assistant can only ever do what you could do yourself.

One URL to paste — OAuth and client registration are automatic

Read and write time entries, review AI suggestions, and manage your data model

Profitability, keywords, tagging settings, Skills, reports, and routines are all reachable

Every action runs as you, with your permissions

Connect in two minutesFull tool reference

Quickstart

1

Add the connector

In Claude Desktop or claude.ai: Settings → Connectors → Add custom connector. Paste https://mcp.rize.io/mcp as the URL. Other clients take the same URL — see Setup per client below.

2

Authorize

Your client opens a browser to sign in to Rize with Google or a magic link, then shows a consent screen naming the client and the redirect URL it will send you back to. Approve it.

3

Orient the assistant

Ask it to call get_current_user, then get_help. Those two tools hand it your timezone, workspace, role, and a guide to the rest of the toolset — which makes every prompt after them noticeably better.

4

Try a prompt

"How much time did I track today?" or "Show me my pending time entry suggestions and approve the ones tagged to Acme."

Connection

Setting	Value
Server URL	https://mcp.rize.io/mcp
Transport	Streamable HTTP
Authentication	OAuth 2.0 (authorization code + PKCE)
Authorization server metadata	https://mcp.rize.io/.well-known/oauth-authorization-server
Protected resource metadata	https://mcp.rize.io/.well-known/oauth-protected-resource
Dynamic client registration	Supported (RFC 7591)

Clients that support dynamic client registration — Claude Desktop, Claude Code, ChatGPT, Cursor, Zed, and anything on the official MCP SDKs — register themselves the first time you connect. There is no client ID or secret for you to create.

Authentication

The server uses the OAuth 2.0 authorization code flow with PKCE. On first connection:

1. Your MCP client requests the server's authorization metadata and registers itself.
2. The client opens your browser to sign in to Rize with Continue with Google or a magic link — the same way you sign in normally.
3. Rize shows a consent screen naming the client, the exact redirect URL it will return you to, and the scopes it is asking for. Denying sends the client an access_denied error and grants nothing.
4. After you approve, the browser redirects back to the client with an authorization code, which it exchanges for an access token.

Access tokens expire after two hours and clients refresh them silently, so you should only need to re-authorize if you disconnect the connector or revoke it from Rize. PKCE is required for every client, public or confidential.

What the assistant can reach

Tokens are issued with the read and write scopes. In practice, the boundary that matters is not the scope — it is your own role:

You are	You get
Any member	Your own time entries, activity, apps used, calendar events, keywords, tagging settings, Skills, reports, and routines.
Team admin	Everything above, plus team-wide time entries and allocation, the team roster, member rates, invites, and labels.
Manager	Your direct reports in the roster and allocation views.
Org admin	Contracts, expenses, revenue entries, and profitability across the workspace.
Finance permission	Profitability reads plus expense and revenue writes, without being an org admin.

An assistant calling a tool you do not have permission for gets an error, not someone else's data. The server never widens access — it forwards your bearer token to the same API the Rize apps call.

Your workspace only

The MCP server operates entirely within the workspaces you belong to. It cannot read another user's data, and it cannot see anything the Rize web app would not show you when signed in as yourself.

Setup per client

Claude Desktop and claude.ai

1. Open Settings → Connectors.
2. Click Add custom connector.
3. Enter the name Rize and the URL https://mcp.rize.io/mcp.
4. Click Add, then Connect next to Rize. A browser window opens.
5. Sign in, approve the consent screen, and return to Claude. The Rize tools are available in any chat.

Claude Code

Register the server:

claude mcp add --transport http rize https://mcp.rize.io/mcp

Or commit a .mcp.json to your project root so the whole team picks it up:

{
  "mcpServers": {
    "rize": {
      "type": "http",
      "url": "https://mcp.rize.io/mcp"
    }
  }
}

Start or restart a session, run /mcp, select rize, and choose Authenticate. A browser window opens; once it says Authorization successful you can close it. Run /mcp again to confirm the connection.

Codex

Add Rize to your project's .mcp.json:

{
  "mcpServers": {
    "rize": {
      "type": "url",
      "url": "https://mcp.rize.io/mcp"
    }
  }
}

Run codex and authenticate when prompted.

ChatGPT

1. Open Settings → Connectors (developer mode may need to be enabled on your plan).
2. Choose to add a connector and enter the MCP server URL https://mcp.rize.io/mcp.
3. Authorize with Continue with Google or a magic link, then approve the consent screen.
4. You land back in ChatGPT with the Rize connector attached.

Zed

Zed runs MCP servers as stdio child processes, so bridge to the remote server with mcp-remote in ~/.config/zed/settings.json:

{
  "context_servers": {
    "rize": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.rize.io/mcp"],
      "env": {}
    }
  }
}

mcp-remote opens a browser for OAuth on first run and caches the token locally.

Any other MCP client

Any client that speaks Streamable HTTP with OAuth 2.0 can connect directly — point it at https://mcp.rize.io/mcp and the rest is negotiated. A typical config entry looks like:

{
  "mcpServers": {
    "rize": {
      "url": "https://mcp.rize.io/mcp"
    }
  }
}

Key names differ per client (url, httpUrl, type, transport), so check your client's documentation for the exact shape. Clients that only support stdio can bridge with mcp-remote, as in the Zed example above.

How to drive it well

These are the things that separate an assistant that gets Rize right from one that guesses.

Start with get_current_user

It returns your timezone, default team, team memberships with roles, and your org id and role. Almost every other tool needs at least one of those, and the profitability tools all need org_id.

Let the server explain itself

get_help returns workflow guides by topic — time tracking, profitability, team management, clients and projects, keywords, skills. get_product_docs searches these docs, so an assistant can answer product questions with a real URL instead of inventing one.

Times are ISO 8601, in your timezone

Every response carries a _user_timezone field. Convert user-relative times ("2pm yesterday") into that zone before sending them — assuming UTC is the single most common source of entries landing on the wrong day.

Use evidence, not vibes, when tagging

list_my_keyword_matches returns deterministic keyword-rule hits over a time window, and list_my_time_entries with include_activity: true attaches top apps, window titles, and overlapping matches per entry. Both are far stronger signals than a title.

Time entry statuses

Time entries move through statuses, and filtering on the wrong one is the usual reason a query comes back empty:

Status	Meaning
tracking	Time being tracked live right now.
segmenting	Tracked activity being cut into candidate entries.
generating	An AI suggestion is being written for the entry.
pending	An AI suggestion waiting for you to approve or reject.
failed	Generation failed; the entry is still reviewable.
active	A confirmed entry — what reports and invoices are built from.
rejected	Dismissed. Retained but hidden from active views.

list_my_time_entries returns everything except rejected by default. When someone says "my suggestions", they mean pending, generating, and failed.

Conventions worth knowing

• IDs, not names. Time entry writes take client_id, project_id, and task_id. Resolve names first with list_clients, list_projects, and list_tasks, all of which accept a query.
• Pagination. List tools take limit and cursor and return has_more and next_cursor. Page until has_more is false rather than raising limit.
• Idempotency. create_time_entry accepts an idempotency_key. Pass one on every create so a retried call cannot double-log an hour.
• Money is in cents. Every monetary value in the contract and profitability tools is an integer number of cents.
• Async AI. generate_time_entries and regenerate_time_entry return immediately and finish in the background. Poll list_my_time_entries with statuses: ["generating", "pending"].
• Preview before saving. add_note with blocks defaults to save: false and returns what it would create, including overlaps with existing entries. Confirm, then call again with save: true.
• Reuse instructions. list_skills and get_skill expose saved Skills, and the agent context tools manage standing guidance for people, teams, and workspaces.
• Read finished AI output. list_report_runs, get_report_run, list_routine_runs, and get_routine_run return report analyses and routine briefs without re-running the same prompt.

Rate limits

Limit	Applies to
100 requests per minute, per user	All authenticated tool calls, across every tool.
10 requests per minute, per tool	The unauthenticated tools, sign_up and get_login_url.
15 per minute and 100 per day	AI generation — generate_time_entries and regenerate_time_entry share one quota.
3 regenerations per entry	regenerate_time_entry, counted for the life of the entry.
20 registrations per minute, per IP	Dynamic client registration during first connect.

Exceeding the per-user limit returns a RATE_LIMITED error carrying retry_after_seconds, so a well-behaved assistant knows exactly how long to wait. The AI generation quotas are enforced by the API and surface as an ordinary error message rather than a RATE_LIMITED code.

Error handling

Every tool error comes back as a JSON object with an error field. The codes an assistant will actually encounter:

Code	Meaning	What to do
AUTHENTICATION_ERROR	No token, or the token is expired or revoked.	Re-authorize the connector.
TOKEN_EXPIRED_ERROR / TOKEN_REVOKED_ERROR / INVALID_TOKEN_ERROR	The bearer token was rejected by the API.	Re-authorize the connector.
RATE_LIMITED	Per-user rate limit hit. Includes retry_after_seconds.	Wait that long, then retry.
SUBSCRIPTION_ERROR	No active subscription on the account.	Surface the message. Do not retry.
INVALID_TIER_ERROR	The workspace plan does not include this capability.	Surface the message. Do not retry.
GRAPHQL_ERROR	Validation failure, missing record, or insufficient permission. Carries a messages array.	Read messages — it names the problem. Correct the input rather than retrying blind.
HTTP_5xx	Transient server error.	Retry once, then surface it.
INTERNAL_ERROR	Unexpected server-side failure.	Surface the message.

GRAPHQL_ERROR is the catch-all: a bad ID, an out-of-range value, and "you must be a team admin" all arrive under it, distinguished by the messages array rather than by code.

Troubleshooting

"Not authenticated" on every call — the token expired or was revoked. Reconnect the connector and sign in again.

The OAuth window opens but never redirects back — some browsers block redirects to 127.0.0.1. Complete the flow in Chrome or Edge, and make sure the callback tab is not blocked by an extension.

Queries return nothing for a day you know you worked — check the status filter first. active alone excludes every AI suggestion. Then check the timezone: a date interpreted in UTC instead of your zone shifts the whole window.

generate_time_entries produces no entries — Rize only generates from tracked activity. If the desktop app was not running for that range, there is nothing to cluster. Very short ranges often produce nothing too; try a full workday.

"Admin only" style errors — list_team_time_entries, get_team_time_allocation, invite_team_member, and the label tools need team admin. The contract and profitability tools need org admin or the finance permission. Use the _my_ variants, or ask an admin.

Stale tool list after an update — some clients cache the tool list. Fully quit and relaunch, then open a new chat.

Example prompts

• "How much time did I track today, grouped by client?"
• "Show me my pending suggestions and approve the ones that are clearly the Acme redesign."
• "What did I actually work on between 2pm and 5pm yesterday? Use my app activity, not just the entry titles."
• "Create a keyword rule so anything with 'Figma' in the window title tags to the Acme project."
• "Log 2 hours on the NVIDIA pitch deck this afternoon."
• "What is the margin on the Acme retainer this quarter, and how much of the included hours have we burned?"
• "Pull my last weekly report run and list every recommendation it made."
• "Read my latest start-of-day routine brief and turn it into a short plan."
• "Use my 'Client profitability review' Skill before summarizing this report run."

Tool reference

Every tool, with parameters, defaults, and permissions.

Reports in the API and MCP

Read finished report and routine runs from an agent instead of re-analyzing raw entries.

Skills and Agent Context

Reuse standing guidance across chat, reports, routines, and MCP clients.

GraphQL API

The same data over a plain API key, for integrations that are not agents.

Rize AI agent

The agent built into Rize, which uses these same capabilities.

Support

• Contact: rize.io/contact
• Privacy policy: rize.io/privacy-policy
• Terms of service: rize.io/terms-of-service