Connecting to Fealthy MCP

Fealthy MCP is stateless MCP Streamable HTTP, JSON-RPC 2.0, on a single endpoint:

POST https://main.api.fealthy.dev/v1/mcp

Any other method on this path (GET, PUT, PATCH, DELETE) returns 405 Method Not Allowed. Authorization is the Authorization: Bearer <personal access token> header. This is not the same token you use to log into the app: it only works on this one endpoint, and the app's GraphQL API doesn't accept it.

Access token

There's no dedicated screen for issuing tokens in the app yet — the Fealthy team issues one on request.

A token is minted at one of two levels:

• Write — all 70 tools, reads and changes alike;
• Read — only list_*/get_* (29 tools); calling a write tool with this token won't work.

Technically the API allows a lifetime from 1 hour to 365 days and up to 5 active tokens at once. The token is shown only once, at the moment it's issued — keep it like a password and never paste it into code that gets committed. If you no longer need it, or it may have leaked, ask the team to revoke it; more detail on the Security page.

Claude Code

claude mcp add -s user -t http fealthy https://main.api.fealthy.dev/v1/mcp -H "Authorization: Bearer fpat_your_token" -H "app-timezone: Europe/Kyiv"

The -s user flag writes the server into your personal ~/.claude.json (it's local to your machine, not in a repo). The app-timezone header is the IANA name of your timezone (for example, Europe/Kyiv); it's needed if your Fealthy profile doesn't have a timezone set yet.

Check the connection:

claude mcp list

You should see a line like fealthy: … (HTTP) - ✔ Connected.

Open a new Claude Code session. A server added in the middle of an already-running session isn't visible to it — the /mcp command only shows tools in a session started after claude mcp add. In the new session, /mcp will list the tools: 70 for a Write-level token, 29 for Read.

Claude Desktop (via mcp-remote)

Claude Desktop can't yet connect to Streamable HTTP with custom headers directly, so the bridge is the mcp-remote package. In claude_desktop_config.json:

{
  "mcpServers": {
    "fealthy": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://main.api.fealthy.dev/v1/mcp",
        "--header",
        "Authorization: Bearer fpat_your_token",
        "--header",
        "app-timezone: Europe/Kyiv"
      ]
    }
  }
}

After saving the file, restart Claude Desktop.

Other clients

Any MCP client that supports the Streamable HTTP transport and lets you set custom request headers will work. The client needs three things: the endpoint URL, an Authorization: Bearer <token> header, and, optionally, an app-timezone header.

For developers

The minimal handshake with no client at all is two curl requests. Both are POST, with Content-Type: application/json and Accept: application/json, text/event-stream (the server always replies with a single JSON object, not an event stream — but the Accept header is what the MCP protocol itself expects).

initialize:

curl -s https://main.api.fealthy.dev/v1/mcp \
  -H "Authorization: Bearer fpat_your_token" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18",
      "capabilities": {},
      "clientInfo": { "name": "curl-example", "version": "1.0.0" }
    }
  }'

The server accepts three protocolVersion values: 2025-11-25, 2025-06-18, and 2025-03-26; for anything unknown it answers with its own latest version rather than an error. The initialize response carries the instructions the server gives the agent (described on the Security page).

tools/list (after the handshake, clients typically add an mcp-protocol-version header with the version from the initialize response; for any request other than initialize itself, an unknown or unsupported value of this header is a 400):

curl -s https://main.api.fealthy.dev/v1/mcp \
  -H "Authorization: Bearer fpat_your_token" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-protocol-version: 2025-06-18" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}'

The number of tools in the response depends on the token's level: 70 for Write, 29 for Read.

Verifying the connection

• claude mcp list (or your client's equivalent) shows a ✔ Connected status.
• /mcp in a new session, or a raw tools/list call, returns the expected tool count for your token's level.
• A simple prompt like "show my accounts" runs without errors.

Common errors