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

Cursor

VS Code

Codex CLI

ChatGPT / Codex Desktop

Devin

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.

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

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 24 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 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 access immediately.
- 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 — Settings → 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.

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

Cursor

VS Code

Codex CLI

ChatGPT / Codex Desktop

Devin

​Prerequisites

​Claude Code

​Prerequisites

​Add the server

​Authorize

​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

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