> ## Documentation Index
> Fetch the complete documentation index at: https://developers.everhour.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Connect an MCP client
> Connect Claude Code, Cursor, VS Code, Codex, ChatGPT, and Devin to the Everhour MCP server over OAuth.
export const zoom = e => {
const o = document.createElement('div');
o.style.cssText = 'position:fixed;inset:0;z-index:9999;display:flex;align-items:center;justify-content:center;background:rgba(0,0,0,.8);cursor:zoom-out';
const v = document.createElement('video');
v.src = e.currentTarget.currentSrc || e.currentTarget.src;
v.autoplay = v.loop = v.muted = v.playsInline = true;
v.style.cssText = 'max-width:80vw;max-height:80vh;border-radius:8px;box-shadow:0 10px 40px rgba(0,0,0,.5)';
o.appendChild(v);
const close = () => {
o.remove();
document.removeEventListener('keydown', k);
};
const k = ev => {
if (ev.key === 'Escape') close();
};
o.addEventListener('click', close);
document.addEventListener('keydown', k);
document.body.appendChild(o);
};
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](/oauth)) and opens your browser to approve access. Pick your client below.
## 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](https://claude.com/claude-code) supports remote MCP servers with OAuth natively.
### Prerequisites
Complete the [prerequisites](#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:
```bash theme={null}
claude mcp add --transport http everhour https://api.everhour.com/mcp
```
### Authorize
1. Run `/mcp` in Claude Code and select **everhour**.
2. Choose **Authenticate**. Your browser opens Everhour's sign-in.
3. Sign in to Everhour, review the consent screen, and click **Allow**.
4. Return to Claude Code — `/mcp` now shows `everhour` as **connected**.
### Verify
Ask Claude: *"What's my Everhour timesheet this week?"* A correct answer means the tools are wired up.
***
## Cursor
[Cursor](https://cursor.com) connects to the Everhour MCP server using its built-in OAuth support.
### Prerequisites
Complete the [prerequisites](#prerequisites). Cursor stores the connection globally or per project — no API key needed.
### Configure Cursor
1. Open **Cursor Settings** (`⌘,` on Mac, `Ctrl+,` on Windows/Linux) → **Tools & MCP**.
2. Click **+ Add new global MCP server** and add the following (this edits `~/.cursor/mcp.json`):
```json theme={null}
{
"mcpServers": {
"everhour": {
"url": "https://api.everhour.com/mcp"
}
}
}
```
### Connect
1. Back in **Tools & MCP**, find `everhour` in the list and click **Connect**.
2. Your browser opens Everhour's sign-in. Sign in, review the consent screen, and click **Allow**.
3. The browser redirects back to Cursor via the `cursor://` protocol handler.
4. Return to Cursor — the server status changes to **connected**.
### 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](#prerequisites). Requires VS Code 1.102 or later.
### Register the server
1. Open the Command Palette (`⌘⇧P` on Mac, `Ctrl+Shift+P` on Windows/Linux) and run **MCP: Add Server**.
2. 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:
```json theme={null}
{
"servers": {
"everhour": {
"type": "http",
"url": "https://api.everhour.com/mcp"
}
}
}
```
### Authorize
1. Start the server — use the **Start** action shown above the entry in `mcp.json`, or accept the prompt when it appears.
2. Your browser opens Everhour's sign-in. Sign in, review the consent screen, and click **Allow**.
3. Return to VS Code — the server shows as **running**.
### Test
Open Chat in **Agent** mode and ask: *"What Everhour projects do I have?"*
***
## Codex CLI
[Codex CLI](https://developers.openai.com/codex/cli) supports remote MCP servers with OAuth natively.
### Prerequisites
Complete the [prerequisites](#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:
```bash theme={null}
curl -fsSL https://chatgpt.com/codex/install.sh | sh # macOS/Linux
# or, with npm:
npm install -g @openai/codex
codex --version
```
### Add the server
```bash theme={null}
codex mcp add everhour --url https://api.everhour.com/mcp
```
### Sign in
Log in to start the OAuth flow:
```bash theme={null}
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.
### 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](#prerequisites). No API key needed — the app handles the OAuth flow for you.
### Add a custom MCP
1. Open **Settings → Plugins → MCPs** and click **Add server**.
2. In the **Connect to a custom MCP** dialog, set:
* **Type:** Streamable HTTP
* **Name:** `everhour`
* **URL:** `https://api.everhour.com/mcp`
3. Click **Save**. `everhour` now appears in the MCP list.
### Authenticate
1. Next to `everhour` in the MCP list, click **Authenticate**.
2. Your browser opens Everhour's sign-in. Sign in, review the consent screen, and click **Allow**.
3. Return to the app — `everhour` shows as connected.
### Test
Ask: *"What's my Everhour timesheet this week?"*
***
## Devin (Windsurf)
[Devin](https://devin.ai/desktop) supports remote MCP servers with OAuth natively.
### Prerequisites
Complete the [prerequisites](#prerequisites). No API key or bridge needed — Devin handles the OAuth flow for you.
### Configure Devin
1. Open the Command Palette (`⌘⇧P` on Mac, `Ctrl+Shift+P` on Windows/Linux) and run **Devin MCP Registry**.
2. On the **MCP Marketplace**, click the gear icon in the top-right of the **Installed MCP** area to open `mcp.json`, then add:
```json theme={null}
{
"mcpServers": {
"everhour": {
"type": "http",
"url": "https://api.everhour.com/mcp"
}
},
"version": 1
}
```
### Authorize
1. Save the config. Devin loads the server and opens your browser to Everhour's sign-in.
2. Sign in, review the consent screen, and click **Allow**.
3. Return to Devin — `everhour` shows as **connected**.
### 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`](https://www.npmjs.com/package/mcp-remote) bridge — run `npx -y mcp-remote@latest https://api.everhour.com/mcp` (needs Node.js).
## Troubleshooting
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.
The server isn't authenticated yet. Run `codex mcp login everhour` to (re)authorize, then check again with `/mcp`.
Restart your client. The server registers 24 tools; a lower count usually means your client cached an older list.
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.
1. Copy your key from [My Profile → API key](https://app.everhour.com/#/account/profile).
2. Add the server with the header (replace `YOUR_API_KEY`):
```json theme={null}
{
"mcpServers": {
"everhour": {
"type": "streamable-http",
"url": "https://api.everhour.com/mcp",
"headers": {
"X-Api-Key": "YOUR_API_KEY"
}
}
}
}
```
Codex uses TOML instead:
```toml theme={null}
[mcp_servers.everhour]
url = "https://api.everhour.com/mcp"
http_headers = { X-Api-Key = "YOUR_API_KEY" }
```
3. 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](/oauth) 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](/oauth-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.