WavePath MCP

Bring your practice diary into your AI client. Read and write diary notes, look up practices and trainings, and pull your statistics from Claude Code, Claude Desktop, Codex, or any MCP-compatible client — over your own scoped personal access token.

$ curl -fsSL https://mcp.wavepath.org | bash

Getting started

Three steps, about a minute.

Mint a token

In WavePath, open Settings › Integrations and create an API token. Pick the scopes you want it to carry.

The raw wave_… secret is shown exactly once — copy it right away.

Run the installer

The one-liner above detects Claude Code and Codex, asks which to configure, and writes the config for you.

Prefer to do it by hand? Every client's config is spelled out below.

Restart your client

Reopen Claude Code, Claude Desktop, or Codex. The wavepath server appears with the tools your token's scopes allow.

Ask it “how did my practice go this week?” to check the wiring.

Configure your client

Replace wave_your_token_here with the token you minted. The token travels only in an Authorization header over HTTPS — never in a URL.

Installer Claude Code Codex Claude Desktop Any MCP client

Interactive — prompts for the token and the client to configure:

$ curl -fsSL https://mcp.wavepath.org | bash

Non-interactive — pass the token and target client as arguments (claude, codex, or both):

$ curl -fsSL https://mcp.wavepath.org | bash -s -- wave_your_token_here codex

Remote HTTP transport — the recommended setup:

$ claude mcp add wavepath \
    --transport http \
    https://mcp.wavepath.org/mcp \
    -H "Authorization: Bearer wave_your_token_here"

Add --scope user to make it available in every project, or --scope project for the current directory only.

Add the server, then keep the token in an env var:

$ codex mcp add --url https://mcp.wavepath.org/mcp \
    --bearer-token-env-var WAVEPATH_TOKEN wavepath

Or write it into ~/.codex/config.toml yourself:

[mcp_servers.wavepath]
url = "https://mcp.wavepath.org/mcp"
bearer_token_env_var = "WAVEPATH_TOKEN"

Then export the token before starting Codex (the installer does this for you, in bash, zsh and fish):

$ export WAVEPATH_TOKEN=wave_your_token_here
# fish: set -gx WAVEPATH_TOKEN wave_your_token_here

Claude Desktop speaks the remote HTTP transport too — add this to claude_desktop_config.json:

{
  "mcpServers": {
    "wavepath": {
      "type": "http",
      "url": "https://mcp.wavepath.org/mcp",
      "headers": { "Authorization": "Bearer wave_your_token_here" }
    }
  }
}

A local stdio transport ships with the source as well, for clients that prefer running the server themselves.

Point any MCP client at the Streamable HTTP endpoint with a bearer header:

Endpoint   https://mcp.wavepath.org/mcp
Transport  Streamable HTTP (SSE)
Auth       Authorization: Bearer wave_your_token_here

Only tokens with the wave_ prefix are accepted; anything else is rejected with a 401 before it reaches the API.

Tools

Tool visibility is scope-gated: a read-only token never even sees the write tools. The API enforces scope on every call regardless.

Tool	Scope	What it does
get_state	any token	Your current context: profile, today's date and note, enabled metrics with ranges, active trainings, today's scheduled practices
get_diary_note	diary:read	Get the diary entry for a date
search_diary_notes	diary:read	Search diary entries by text and date range
create_diary_note	diary:write	Create the diary entry for a date
update_diary_note	diary:write	Update the diary entry for a date
search_practices	practices:read	Search practices by text, type, ownership and favourite status
get_practice	practices:read	Get a practice by id
list_trainings	trainings:read	List trainings by text and date range
get_training	trainings:read	Get a training by slug
get_statistics	stats:read	Practice statistics for a date range

Guided note

Tokens that can write also get a prompt, not just tools.

create_wavepath_note — a guided interview that reads your current state, then asks one short question at a time: how the day went, which practices you did and for how long, a value for each of your enabled metrics, an overall score and keywords. It shows you a summary and only writes the note once you confirm.

In Claude Code, run /wavepath:create_wavepath_note.
Requires the diary:write scope.

How your token is handled

The MCP server is a thin proxy. It holds no business logic and makes no authorization decision of its own.

Your token is forwarded to the WavePath API, which is the sole authority on auth, scope, ownership and expiry.
It is never embedded in a URL — only in an Authorization: Bearer header, over HTTPS.
The installer never puts your token in the install URL; you pass it as an argument or type it at the prompt.
Server logs record a session-id prefix only — never the token.
Scope it down to what you actually need, and revoke it any time from Settings › Integrations.

Endpoints

For anyone wiring this up by hand or monitoring it.

POST https://mcp.wavepath.org/mcpMCP Streamable HTTP transport. Requires a wave_ bearer token.

GET https://mcp.wavepath.org/healthLiveness JSON: status, version, active session count.

GET https://mcp.wavepath.org/This page in a browser; the install script to curl.

GET https://api.wavepath.org/api/v1/*The public token API this server proxies.

Ready?

Mint a token, run the one-liner, restart your client.

Get your token →