Connect an MCP client

The Everhour MCP server works with any client that speaks the MCP Streamable HTTP transport. The server URL is the same everywhere:

https://api.everhour.com/mcp

Clients connect with OAuth 2.1. You don’t register an application or manage a client ID and secret — the first time a client connects, Everhour registers it automatically (Dynamic Client Registration) and opens your browser to approve access. Pick your client below.

Claude Code

Claude Desktop

Cursor

VS Code

Codex CLI

ChatGPT / Codex Desktop

Devin

This page covers the mechanics. For what to ask Claude once it’s connected — example prompts and the interactive cards — see Everhour in Claude.

Prerequisites

An active Everhour account. You can sign in with Google, SAML SSO, or email and password.

There’s nothing to set up in Everhour ahead of time — no app to create, no credentials to copy, no redirect URL to register. Authorization happens in your browser when you connect.

Claude Code

Claude Code supports remote MCP servers with OAuth natively.

Prerequisites

Complete the prerequisites. No API key or app registration needed — Claude Code handles the OAuth flow for you.

Add the server

Add the server with one command:

claude mcp add --transport http everhour https://api.everhour.com/mcp

Authorize

Run /mcp in Claude Code and select everhour.
Choose Authenticate. Your browser opens Everhour’s sign-in.
Sign in to Everhour, review the consent screen, and click Allow.
Return to Claude Code — /mcp now shows everhour as connected.

Connecting Everhour in Claude Code

Verify

Ask Claude: “What’s my Everhour timesheet this week?” A correct answer means the tools are wired up.

Claude Desktop

The Claude desktop app and claude.ai add Everhour as a custom connector. The steps are the same in both, and in the mobile apps.

The whole flow: adding the connector, approving access in Everhour, then asking for the running timer

Prerequisites

Complete the prerequisites. No API key or app registration needed. Which path you take depends on your Claude plan:

Your plan	What you do
Free, Pro, or Max	Add the connector yourself — follow everything below.
Team or Enterprise, and you’re an Owner	Add it once for the organization: Organization settings → Connectors → Add → Custom, choosing Web if you’re asked for a type. Then tell your team to use the short path.
Team or Enterprise, and you’re not an Owner	You can’t add a custom connector, and you don’t need to. Skip to If someone already added it.

Add the connector

Open Customize → Connectors in the left sidebar, then click + next to Connectors.
Give it a name — Everhour — and enter the server URL:
https://api.everhour.com/mcp
Click Continue. Claude checks the URL and fills in the authentication it finds, marked Detected — for Everhour that’s Sign in now and Register automatically. Leave both as detected; there’s no client ID or secret to paste, because Everhour registers your client itself.
Click Add.

Older builds label this Settings → Connectors.The two-step dialog is still rolling out. If yours puts the name, URL, and Advanced settings on a single screen, leave Advanced settings alone and click Add — there’s nothing to change there either way.

If someone already added it

On a Team or Enterprise plan, your Owner adds Everhour once for everyone. When they have, open Customize → Connectors, find Everhour in the list, and click Connect — there’s no URL to paste and no name to pick. Then carry on with Authorize below.

Authorize

Click Connect next to Everhour.
Your browser opens Everhour’s sign-in. Sign in, review the consent screen, and click Allow.
Everhour shows as connected.

Enable it in a chat

Connectors are switched on per conversation. Click + at the lower left of the chat box, choose Connectors, and turn Everhour on.

Switching Everhour on for a conversation

Verify

Ask: “What’s my Everhour timesheet this week?”

Cursor

Cursor connects to the Everhour MCP server using its built-in OAuth support.

Prerequisites

Complete the prerequisites. Cursor stores the connection globally or per project — no API key needed.

Configure Cursor

Open Cursor Settings (⌘, on Mac, Ctrl+, on Windows/Linux) → Tools & MCP.

Click + Add new global MCP server and add the following (this edits ~/.cursor/mcp.json):

{
  "mcpServers": {
    "everhour": {
      "url": "https://api.everhour.com/mcp"
    }
  }
}

Connect

Back in Tools & MCP, find everhour in the list and click Connect.
Your browser opens Everhour’s sign-in. Sign in, review the consent screen, and click Allow.
The browser redirects back to Cursor via the cursor:// protocol handler.
Return to Cursor — the server status changes to connected.

Adding the Everhour MCP server in Cursor

Test

Open a new agent window and ask: “Show my Everhour tasks I tracked this week.”

VS Code

VS Code supports MCP servers with OAuth natively (VS Code 1.102 or later).

Prerequisites

Complete the prerequisites. Requires VS Code 1.102 or later.

Register the server

Open the Command Palette (⌘⇧P on Mac, Ctrl+Shift+P on Windows/Linux) and run MCP: Add Server.
Choose HTTP, enter the URL https://api.everhour.com/mcp, and name it everhour. You can also add it directly to .vscode/mcp.json — note VS Code uses the servers key:
{ "servers": { "everhour": { "type": "http", "url": "https://api.everhour.com/mcp" } } }

Authorize

Start the server — use the Start action shown above the entry in mcp.json, or accept the prompt when it appears.
Your browser opens Everhour’s sign-in. Sign in, review the consent screen, and click Allow.
Return to VS Code — the server shows as running.

Adding the Everhour MCP server in VS Code

Test

Open Chat in Agent mode and ask: “What Everhour projects do I have?”

Codex CLI

Codex CLI supports remote MCP servers with OAuth natively.

Prerequisites

Complete the prerequisites. No API key needed — Codex handles the OAuth flow for you.

Install the CLI

Install the Codex CLI, then verify it’s on your PATH:

curl -fsSL https://chatgpt.com/codex/install.sh | sh   # macOS/Linux
# or, with npm:
npm install -g @openai/codex

codex --version

Add the server

codex mcp add everhour --url https://api.everhour.com/mcp

codex mcp login everhour

Your browser opens Everhour’s sign-in. Sign in, review the consent screen, and click Allow — then return to the terminal.

Connecting Everhour in Codex CLI

Test

Run codex, then /mcp — confirm everhour is listed and authenticated. Ask: “What did I track in Everhour today?”

ChatGPT / Codex Desktop

OpenAI’s desktop app — which combines ChatGPT and Codex — supports custom MCP servers over OAuth.

Prerequisites

Complete the prerequisites. No API key needed — the app handles the OAuth flow for you.

Add a custom MCP

Open Settings → Plugins → MCPs and click Add server.
In the Connect to a custom MCP dialog, set:
- Type: Streamable HTTP
- Name: everhour
- URL: https://api.everhour.com/mcp
Click Save. everhour now appears in the MCP list.

Authenticate

Next to everhour in the MCP list, click Authenticate.
Your browser opens Everhour’s sign-in. Sign in, review the consent screen, and click Allow.
Return to the app — everhour shows as connected.

Connecting Everhour in ChatGPT / Codex Desktop

Test

Ask: “What’s my Everhour timesheet this week?”

Devin (Windsurf)

Devin supports remote MCP servers with OAuth natively.

Prerequisites

Complete the prerequisites. No API key or bridge needed — Devin handles the OAuth flow for you.

Configure Devin

Open the Command Palette (⌘⇧P on Mac, Ctrl+Shift+P on Windows/Linux) and run Devin MCP Registry.

On the MCP Marketplace, click the gear icon in the top-right of the Installed MCP area to open mcp.json, then add:

{
  "mcpServers": {
    "everhour": {
      "type": "http",
      "url": "https://api.everhour.com/mcp"
    }
  },
  "version": 1
}

Authorize

Save the config. Devin loads the server and opens your browser to Everhour’s sign-in.
Sign in, review the consent screen, and click Allow.
Return to Devin — everhour shows as connected.

Connecting Everhour in Devin

Verify

Ask: “What’s my Everhour timesheet this week?”

Other clients

Any MCP client that supports remote servers with OAuth — including Claude connectors — works with the same URL. Add https://api.everhour.com/mcp as a remote/HTTP server and complete the sign-in and click Allow when prompted. Clients that only speak stdio can use the mcp-remote bridge — run npx -y mcp-remote@latest https://api.everhour.com/mcp (needs Node.js).

Troubleshooting

Signing in never finishes

Make sure pop-ups aren’t blocked and that you finish the Allow step in the browser tab your client opened. If the consent page reports an expired request, start the connection again from your client.

Codex CLI shows no Everhour tools

The server isn’t authenticated yet. Run codex mcp login everhour to (re)authorize, then check again with /mcp.

Tool count looks wrong after an update

Restart your client. The server registers 28 tools; a lower count usually means your client cached an older list.

Reconnecting fails with an “invalid client” error

Your client cached a registration from an earlier connection that Everhour no longer recognizes, so authorization keeps failing. Clear the cached client, then add the server again:

Claude Desktop and claude.ai: open Customize → Connectors, remove Everhour, then add it again. On Team and Enterprise an Owner has to do this under Organization settings → Connectors.
Claude Code: claude mcp logout everhour, then claude mcp remove everhour, then re-run claude mcp add --transport http everhour https://api.everhour.com/mcp.
Codex CLI: codex mcp logout everhour, then codex mcp remove everhour, then codex mcp add everhour --url https://api.everhour.com/mcp.
Cursor / VS Code / Devin: remove the everhour block from the config (and clear any stored authorization), then add it again to force a fresh registration.

Disconnecting

Remove the server in your client. This discards its stored tokens and stops it refreshing them.
- Claude Code: claude mcp logout everhour, then claude mcp remove everhour.
- Cursor / VS Code / Devin: delete the everhour block from the config and restart.
- Codex CLI: codex mcp logout everhour, then codex mcp remove everhour.
In a desktop or chat app: ChatGPT / Codex Desktop — Settings → Plugins → MCPs and remove everhour; Claude Desktop and claude.ai — Customize → Connectors and remove the Everhour connector.

Access tokens are short-lived and refresh automatically while a client stays connected. Removing the server stops the refresh, so access ends once the current token expires — within an hour, not instantly. Everhour has no revocation endpoint yet; see Data, privacy, and permissions.

Connect with an API key

If a client can’t do OAuth — or you’re wiring up automation and want a headless connection — you can authenticate with an Everhour API key in an X-Api-Key header instead.

An API key never expires on its own and grants full access to your account. Prefer OAuth wherever your client supports it, and never commit the key to a repository.

Copy your key from My Profile → API key.

Add the server with the header (replace YOUR_API_KEY):

{
  "mcpServers": {
    "everhour": {
      "type": "streamable-http",
      "url": "https://api.everhour.com/mcp",
      "headers": {
        "X-Api-Key": "YOUR_API_KEY"
      }
    }
  }
}

Codex uses TOML instead:

[mcp_servers.everhour]
url = "https://api.everhour.com/mcp"
http_headers = { X-Api-Key = "YOUR_API_KEY" }

Restart the client. To revoke access, regenerate the key in your profile — every client using the old key loses access at once.

How authorization works

You don’t need this to connect, but if you’re building or debugging a client, the OAuth 2.1 section walks through the whole flow — discovery, Dynamic Client Registration, the authorization code + PKCE exchange, and token refresh — with a sequence diagram. The OAuth 2.1 reference lists every endpoint and parameter. MCP clients request the https://api.everhour.com/mcp resource, so their token is audience-bound to this server.

Claude Code

Claude Desktop

Cursor

VS Code

Codex CLI

ChatGPT / Codex Desktop

Devin

​Prerequisites

​Claude Code

​Prerequisites

​Add the server

​Authorize

​Verify

​Claude Desktop

​Prerequisites

​Add the connector

​If someone already added it

​Authorize

​Enable it in a chat

​Verify

​Cursor

​Prerequisites

​Configure Cursor

​Connect

​Test

​VS Code

​Prerequisites

​Register the server

​Authorize

​Test

​Codex CLI

​Prerequisites

​Install the CLI

​Add the server

​Sign in

​Test

​ChatGPT / Codex Desktop

​Prerequisites

​Add a custom MCP

​Authenticate

​Test

​Devin (Windsurf)

​Prerequisites

​Configure Devin

​Authorize

​Verify

​Other clients

​Troubleshooting

​Disconnecting

​Connect with an API key

​How authorization works

Prerequisites

Claude Code

Prerequisites

Add the server

Authorize

Verify

Claude Desktop

Prerequisites

Add the connector

If someone already added it

Authorize

Enable it in a chat

Verify

Cursor

Prerequisites

Configure Cursor

Connect

Test

VS Code

Prerequisites

Register the server

Authorize

Test

Codex CLI

Prerequisites

Install the CLI

Add the server

Sign in

Test

ChatGPT / Codex Desktop

Prerequisites

Add a custom MCP

Authenticate

Test

Devin (Windsurf)

Prerequisites

Configure Devin

Authorize

Verify

Other clients

Troubleshooting

Disconnecting

Connect with an API key

How authorization works