MCP setup and troubleshooting

Connect any compatible MCP client to Vitalog’s Streamable HTTP endpoint.

Use your API’s MCP URL, such as https://vitalog-api.example.com/mcp. The UI address is where you sign in and review records; it is not the MCP endpoint.

Open Account Settings → MCP Guide in Vitalog to copy configurations for your installation. The examples below use the example API hostname. Replace it when self-hosting.

Connect with OAuth

Add the MCP URL to a client that supports Streamable HTTP and MCP authorization. The client discovers the authorization server, registers or supplies its client metadata, and opens Vitalog’s consent page. Sign in with the root email and password, review the requesting client’s identity, callback destination and requested access, then approve.

The client receives its token through the OAuth callback and token exchange. You do not need to create or paste an API key. Tokens expire after 30 days; reconnect after expiry. Revoke a connection from Account Settings → MCP Connections after verifying your root credentials.

Codex

Add this to ~/.codex/config.toml:

[mcp_servers.vitalog]
url = "https://vitalog-api.example.com/mcp"

Run codex mcp login vitalog to sign in.

Claude Code

claude mcp add --transport http vitalog 'https://vitalog-api.example.com/mcp'

Open /mcp in Claude Code and select Vitalog to sign in.

Cursor

Add this to .cursor/mcp.json:

{
  "mcpServers": {
    "vitalog": {
      "url": "https://vitalog-api.example.com/mcp"
    }
  }
}

Connect the server in Cursor’s MCP settings and complete the sign-in flow.

VS Code

Add this to .vscode/mcp.json:

{
  "servers": {
    "vitalog": {
      "type": "http",
      "url": "https://vitalog-api.example.com/mcp"
    }
  }
}

Start the server and approve the sign-in prompt.

Other clients can use the same URL and OAuth discovery. Vitalog follows the MCP authorization specification independently of the client’s brand. See the OAuth contract for registration, PKCE, scopes and callback requirements.

OAuth authorization only

MCP accepts only OAuth access tokens granted through sign-in and consent. Personal API keys, the operator AUTH_KEY, and dashboard sessions cannot authenticate MCP. Read tools require health:read; record and goal changes require health:write.

If you previously used an API key, remove its custom authorization header or bearer-token environment setting and reconnect through OAuth. REST integrations can keep using their API keys.

Tool discovery and calls

Vitalog uses stateless Streamable HTTP with JSON responses. For raw MCP POST requests, send Accept: application/json, text/event-stream. The official SDK negotiates the protocol version. Clients initialize, list tools and call the MCP tools; logging, discovery, reading, correction and goals share the REST domain service.

Troubleshooting

Symptom	Check
Sign-in works, but tools do not appear	Use the API’s /mcp endpoint. Reconnect to refresh discovery, then inspect the client’s initialization and tools/list errors.
HTTP 401	The token is missing, expired or revoked. Reconnect through OAuth and approve access again.
HTTP 403 on a write	The OAuth connection needs health:write; review the scopes before reconnecting.
The callback is rejected	The callback must match registered client metadata and the resource must be the exact MCP URL.
A browser client is blocked by CORS	Ask the operator to allow that exact origin in ALLOWED_ORIGINS; UI consent requests use UI_BASE_URL.
HTTP 429	Wait for Retry-After, then retry with the same idempotency key and original arguments for a write.

Check your client’s current documentation for client-specific connection controls: Codex, Claude Code, Cursor and VS Code.