Hiddenden/familiar

0 Fork 0

Files

T

Latte df9e06a3e7

CI / lint (pull_request) Successful in 55s

Details

docker / lint (pull_request) Successful in 56s

Details

CI / test (pull_request) Successful in 1m6s

Details

docker / test (pull_request) Successful in 1m4s

Details

CI / publish (pull_request) Has been skipped

Details

docker / docker (pull_request) Failing after 1m11s

Details

docs: deployment guide + per-client setup + connect matrix

- doc/deployment.md: run familiar as a remote MCP server — secure defaults,
  bearer vs OAuth modes, the full env-var reference, one-time login / token-store
  provisioning, the published images, docker compose, and TLS reverse-proxy
  blocks for nginx (proxy_buffering off + long read timeout), Caddy, and Traefik.
- doc/clients/: one page per client with exact working steps — Claude Code,
  VS Code (.vscode/mcp.json with a masked token input, and the workspace
  .mcp.json header gotcha), Mistral Le Chat, Claude Desktop + Cowork (mcp-remote
  bridge, per-OS config paths), and Claude web (oauth mode + external IdP, with
  "use Desktop + bearer" as the simpler alternative). Plus a clients/ index.
- README: a "Connect a client" matrix (client -> auth -> guide) and a compact
  "Deploy with Docker" section linking to doc/deployment.md; oauth mode noted.
- doc/README.md index: rows for Deployment and Client setup.
- doc/getting-started.md: pointer from the HTTPS quickstart to the full docs.
- CLAUDE.md: FAMILIAR_AUTH_MODE / FAMILIAR_OAUTH_* / FAMILIAR_ALLOW_INSECURE_BIND
  and /healthz in the transport note; the split ci.yml / docker.yml workflows.

Deployment docs live under the existing doc/ tree (the repo uses doc/, not a
separate docs/) to keep a single documentation directory.

2026-07-04 19:26:33 +02:00

1.5 KiB

Raw Blame History

Connect Claude Desktop

Auth: bearer token, via a local bridge. Prereq: familiar deployed over HTTPS (see deployment), plus Node.js (npx) on the machine running Claude Desktop.

Claude Desktop's Connectors UI can add a remote MCP URL but cannot attach a bearer header. So bridge the remote HTTP server to a local stdio command with mcp-remote, which forwards the Authorization header.

Edit claude_desktop_config.json:

{
  "mcpServers": {
    "familiar": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://familiar.yourdomain.tld/mcp",
        "--header",
        "Authorization: Bearer <your-token>"
      ]
    }
  }
}

Config file location:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Restart Claude Desktop fully (quit, not just close the window). familiar appears in the tools/plug icon.

Troubleshooting

Server fails to start — ensure Node.js is installed and npx is on PATH; the first run downloads mcp-remote.
401 — fix the token in the --header argument, then restart.
Want native (no bridge)? Only the OAuth path is header-free, and Desktop's connector is happiest with bearer via this bridge — keep mcp-remote unless you've set up oauth mode.

1.5 KiB Raw Blame History

Connect Claude Desktop

Troubleshooting

1.5 KiB

Raw Blame History