{ "markdown": "\n\n

\n \"Althea\"\n

\n\n

Althea MCP

\n\n

\n A direct line from your coding agent to your Althea.
\n Shared research memory and a consent-first network of verified ML researchers.\n

\n\n

\n \"CI\n \"Latest\n \"PyPI\n \"Python\n \"MCP\n \"MIT\n

\n\nGive Codex, Claude Code, and other coding agents a direct line to your personal\n[Althea](https://althea.tiptreesystems.com). They can hand her questions, code,\nand context from the repository in front of them. Althea brings your shared\nresearch memory and, when useful, can ask a consent-first network of verified\nML researchers for help.\n\n- **Agents that can talk to each other.** Pass questions, code, experiment\n results, and repository context between your coding agent and Althea.\n- **Your Althea, with your context.** MCP uses your existing account, profile,\n and long-term research memory.\n- **A route into the researcher network.** Althea can ask verified ML\n researchers for help, with consent before private context is shared.\n- **Client-specific conversations.** Codex and Claude stay separate when you\n give them distinct thread keys, while Althea keeps your shared context.\n- **Work asynchronously.** Wait for a reply, leave a message for longer work,\n or read the thread later.\n\n[Setup](#setup) · [Connect a client](#connect-an-mcp-client) ·\n[First conversation](#start-a-conversation) · [Tools](#tools) ·\n[Security and privacy](#security-and-privacy) ·\n[Development](#local-development)\n\n## Setup\n\nYou need access to Althea and [uv](https://docs.astral.sh/uv/getting-started/installation/).\nInstall Althea MCP from PyPI, then sign in with an emailed verification code:\n\n```bash\nuv tool install althea-mcp\nalthea-mcp setup\n```\n\nIf the install succeeds but the command is not found, run `uv tool update-shell`\nand open a new terminal.\n\nRun setup yourself in an interactive terminal. Enter your email and verification\ncode there, not in an AI chat.\n\n```text\nConnect your personal Althea\n-----------------------------\nEmail: you@example.com\nA verification code was sent to you@example.com.\nVerification code:\n\nAlthea MCP is ready.\nCredentials saved to ~/.config/althea-mcp/credentials.json\n```\n\nSetup follows the same account journey as the Althea web app:\n\n- Existing accounts receive a verification code by email.\n- Eligible new accounts are asked for a name, then receive a verification code.\n- Accounts that still need access are sent to the\n [Althea application](https://tiptreesystems.com/apply). Complete it, then run\n setup again.\n\nThe installed server starts without fetching code on every launch. Its tools\nstill need a network connection to Althea. Upgrade the package later with:\n\n```bash\nuv tool upgrade althea-mcp\n```\n\n## Connect an MCP client\n\nComplete setup once, then add the local stdio server. Give each client a\ndifferent thread key.\n\n> [!CAUTION]\n> This server can read private Althea history and send real messages. Register\n> it only in clients and projects you trust.\n\n### Codex\n\n```bash\ncodex mcp add althea \\\n --env ALTHEA_THREAD_KEY=codex \\\n -- althea-mcp\ncodex mcp list\n```\n\n`codex mcp add` writes to your user configuration. Equivalent\n`~/.codex/config.toml`:\n\n```toml\n[mcp_servers.althea]\ncommand = \"althea-mcp\"\n\n[mcp_servers.althea.env]\nALTHEA_THREAD_KEY = \"codex\"\n```\n\n### Claude Code\n\n```bash\nclaude mcp add althea \\\n -e ALTHEA_THREAD_KEY=claude-code \\\n -- althea-mcp\nclaude mcp list\n```\n\nThat command uses Claude Code's project-local scope. Add `--scope user`\nimmediately before `althea` only if you want the server available in every\nproject you open.\n\nA user-wide manual entry under the top-level `mcpServers` object in\n`~/.claude.json` looks like this:\n\n```json\n{\n \"mcpServers\": {\n \"althea\": {\n \"type\": \"stdio\",\n \"command\": \"althea-mcp\",\n \"env\": {\n \"ALTHEA_THREAD_KEY\": \"claude-code\"\n }\n }\n }\n}\n```\n\n### Claude Desktop and other local clients\n\nFind the installed command:\n\n```bash\ncommand -v althea-mcp\n```\n\nOn Windows PowerShell:\n\n```powershell\n(Get-Command althea-mcp).Source\n```\n\nGUI applications sometimes receive a smaller `PATH` than your terminal. If\n`althea-mcp` is not found, use the absolute path returned above:\n\n```json\n{\n \"mcpServers\": {\n \"althea\": {\n \"command\": \"/absolute/path/to/althea-mcp\",\n \"env\": {\n \"ALTHEA_THREAD_KEY\": \"claude-desktop\"\n }\n }\n }\n}\n```\n\nRestart the client after changing its MCP configuration.\n\n## Start a conversation\n\nTry one of these prompts in your MCP client:\n\n```text\nAsk my Althea whether anyone in the researcher network has worked on this\nfailure mode. Share only the sanitized summary below:\n[summary]\n```\n\n```text\nSend this context to my Althea without waiting for a reply:\nThe latest experiment rules out the data-loader hypothesis. The remaining\nfailure starts after gradient accumulation.\n```\n\n```text\nCheck whether my Althea has replied in the MCP thread.\n```\n\nMessages continue the configured thread. They are real messages to your\npersonal Althea and may cause her to begin work.\n\n## Tools\n\n| Tool | What it does |\n| --- | --- |\n| `ask_althea(message)` | Sends a message and uses a 120-second polling window by default for the first reply. If the window expires, the work may still continue. |\n| `send_message_to_althea(message)` | Sends a message immediately and returns a receipt without waiting. Use it for context, notes, and longer requests. |\n| `get_althea_messages(sender=None, limit=10)` | Returns 1 to 100 recent messages in chronological order. Optionally filter by `user`, `assistant`, or `system`. |\n| `search_althea_conversations(query=None, limit=10)` | Finds conversations across the user's Althea account by title or topic. With no query, returns recent conversations. |\n| `get_althea_conversation_log(conversation_id, limit=100)` | Returns the last 1 to 100 messages from any owned conversation in chronological order, together with its total message count. |\n\nThe two send tools are marked as state-changing. Conversation search and message\nretrieval are read-only. The current tool surface is text-only. It does not\nexpose attachments or other Althea artifacts.\n\n## How it works\n\n```text\nCodex / Claude Code / another coding agent\n │ local stdio\n ▼\n Althea MCP\n │ HTTPS\n ▼\n your Althea\n │\n ├── your profile and long-term research memory\n ├── a persisted conversation for this thread key\n └── a consent-first network of verified ML researchers\n```\n\nAlthea MCP is a small public adapter. The frontend authenticates the user,\nresolves their canonical Althea, sends messages, and stores the resulting\nconversation. The package polls those persisted messages when a caller waits\nfor a reply. The coding agent talks to Althea, and Althea coordinates with the\nresearcher network when a request would benefit from outside expertise.\n\n## Sign-in and sessions\n\nSetup creates a normal Althea usage session:\n\n- The access session lasts 7 days.\n- Its rotating refresh-token family lasts 14 days from sign-in.\n- Access tokens refresh automatically before expiry.\n- A cross-process lock lets several local MCP clients share the credential file\n without racing refresh-token rotation.\n- When the session expires or is revoked, run `althea-mcp setup` again in a\n separate terminal. Running MCP processes reload the replacement credentials.\n- Signing in again rotates credentials only. It does not replace conversation\n history when the Althea account and `ALTHEA_THREAD_KEY` stay the same.\n\nCredentials are stored as plaintext JSON at\n`~/.config/althea-mcp/credentials.json`. On operating systems that support Unix\nfile modes, the credential file is set to `0600`. A parent directory created by\nAlthea MCP is requested as `0700`; check the permissions yourself when using a\npre-existing custom directory.\n\n## Security and privacy\n\n- Messages sent through these tools are persisted in your Althea account, like\n messages from Althea's other channels.\n- The local stdio process sends messages and credentials to Althea over HTTPS.\n Even with local transport, conversation data leaves your machine.\n- The connected MCP host and model can see tool arguments and replies. They may\n retain that data under their own privacy and retention policies.\n- When Althea asks the researcher network for help, she requests consent before\n sharing information drawn from a private conversation.\n- The package sends access credentials only to the Althea origin they were\n issued for. Changing `ALTHEA_APP_URL` requires a new setup.\n- The refresh token is sent only to the session rotation endpoint.\n- Email verification codes and the credential file are secrets. Never paste\n them into an AI chat, terminal transcript, issue, or pull request.\n- To remove the local session, close MCP clients and delete the credential file.\n This forgets the session on that machine. Contact Tiptree if a copied session\n must also be revoked.\n\nPlease report vulnerabilities using\n[the security policy](https://github.com/tiptreesystems/althea-mcp/security/policy).\n\n## Configuration\n\nMost users only need `althea-mcp setup` and a client-specific thread key.\n\n| Environment variable | Default | Purpose |\n| --- | --- | --- |\n| `ALTHEA_APP_URL` | `https://althea.tiptreesystems.com` | Althea API origin. Saved credentials are bound to it. Plain HTTP is accepted only for loopback development. |\n| `ALTHEA_PUBLIC_SITE_URL` | `https://tiptreesystems.com` | Base URL for terms, privacy, and access requests. Dev Althea selects `https://dev.tiptreesystems.com` automatically. |\n| `ALTHEA_THREAD_KEY` | `mcp` | Stable conversation identifier. Use 1 to 128 letters, digits, dots, underscores, colons, or hyphens, starting with a letter or digit. |\n| `ALTHEA_MCP_CREDENTIALS_FILE` | `~/.config/althea-mcp/credentials.json` | Override the local credential path. |\n| `ALTHEA_MCP_HTTP_TIMEOUT` | `60` | HTTP timeout in seconds. |\n| `ALTHEA_MCP_POLL_INTERVAL` | `2` | Delay between response polls in seconds. |\n| `ALTHEA_MCP_POLL_TIMEOUT` | `120` | Maximum wait for `ask_althea` in seconds. |\n| `ALTHEA_MCP_LOG_LEVEL` | `WARNING` | Python log level. |\n\nSetup also accepts `--credentials-file` to override the credential path and\n`--no-browser` to print an access-request URL without opening it.\n\n## Troubleshooting\n\n**`Althea MCP is not configured`**\n\nRun `althea-mcp setup` in a terminal, then restart the MCP client.\n\n**`Your Althea MCP sign-in has expired or was revoked`**\n\nRun setup again. The refresh-token family has a 14-day absolute lifetime.\n\n**Saved credentials are bound to another URL**\n\nRun setup with the same origin the MCP client will use:\n\n```bash\nalthea-mcp setup --app-url https://althea.example\n```\n\nThen set the matching `ALTHEA_APP_URL` in the client configuration.\n\n**`ask_althea` timed out**\n\nAlthea may still be working. Call `get_althea_messages` after a short wait.\n\n**The client cannot find `althea-mcp`**\n\nRun `command -v althea-mcp` in a terminal and use that absolute path in the\nclient configuration.\n\n**Two clients are sharing a conversation**\n\nAssign a distinct `ALTHEA_THREAD_KEY` to each client and restart them.\n\n## Local development\n\n```bash\ngit clone https://github.com/tiptreesystems/althea-mcp.git\ncd althea-mcp\nuv sync --locked --extra dev\nuv run pytest -q\nuv run ruff check althea_mcp tests\nuv run ruff format --check .\nuv build\nuvx twine check dist/*\n```\n\nRun setup against a local frontend:\n\n```bash\nuv run althea-mcp setup --app-url http://localhost:8080\n```\n\nRunning `althea-mcp` with no subcommand starts the stdio server. The explicit\nequivalent is `althea-mcp serve`.\n\n## Contributing\n\nBug reports and focused pull requests are welcome. Read\n[the contribution guide](https://github.com/tiptreesystems/althea-mcp/blob/main/CONTRIBUTING.md)\nbefore opening one. Remove all email addresses, messages, OTPs, and credentials\nfrom logs and fixtures.\n\n## License\n\n[MIT](https://github.com/tiptreesystems/althea-mcp/blob/main/LICENSE) © Tiptree\nAdvanced Systems Corporation.\n", "bytes": 13342, "sha": "d4742e47387f788f3c684b867d5468e478721baa0f254cd566b7b7101328be0c", "repo_slug": "tiptreesystems/althea-mcp", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_tiptreesystems_althea_mcp_f40b4dce/readme" }