Althea MCP

io.github.tiptreesystemsPublished by GitHub account tiptreesystemsv0.2.1Updated Oct 25, 2026

Connect coding agents to your Althea and, through her, a consent-first network of ML researchers.

VerifiedSTDIODesktop onlyKnowledge & MemoryCommunication & CollaborationAI & ML

Overview

AI-generated overview

A local stdio MCP server that connects coding agents such as Codex and Claude Code to the user's personal Althea assistant for shared research memory and help.

What you can do
Send questions, code and repository context to Althea, either waiting for a first reply or sending without waiting and getting a receipt back. Read recent messages in the configured thread, optionally filtered by sender. Search the user's Althea conversations by title or topic, or list recent ones. Retrieve the message log of any owned conversation, with its total message count. Althea may in turn consult a consent-first network of verified ML researchers.
When to use it
Useful when a coding agent should hand questions, experiment results or repository context to a personal Althea and draw on shared research memory, including asynchronous follow-ups and occasional outside researcher input. Register it only in clients and projects you trust.
Requirements
Runs as a local process installed from PyPI with uv; access to Althea is required. Run the setup command once in an interactive terminal and sign in with an emailed verification code; existing accounts, eligible new accounts and accounts needing access follow different paths. Tools need a network connection to Althea over HTTPS. Optional environment variables set the app URL, thread key, credential file path, timeouts and log level.
Before you install
The server can read private Althea history and send real messages that may cause Althea to begin work. Messages are persisted in the Althea account and conversation data leaves the machine over HTTPS; the MCP host and model can see tool arguments and replies. Credentials are stored as plaintext JSON in a local file, and email verification codes and that file are secrets that should not be pasted into chats or transcripts. When Althea asks the researcher network for help, she requests consent, so

Installation

In SourceWeft

  1. Open Althea MCP in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

[Althea]

Althea MCP

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

[CI status] [Latest GitHub release] [PyPI version] [Python 3.11+] [MCP Registry listing] [MIT license]

Give Codex, Claude Code, and other coding agents a direct line to your personal Althea. They can hand her questions, code, and context from the repository in front of them. Althea brings your shared research memory and, when useful, can ask a consent-first network of verified ML researchers for help.

  • Agents that can talk to each other. Pass questions, code, experiment results, and repository context between your coding agent and Althea.
  • Your Althea, with your context. MCP uses your existing account, profile, and long-term research memory.
  • A route into the researcher network. Althea can ask verified ML researchers for help, with consent before private context is shared.
  • Client-specific conversations. Codex and Claude stay separate when you give them distinct thread keys, while Althea keeps your shared context.
  • Work asynchronously. Wait for a reply, leave a message for longer work, or read the thread later.

Setup · Connect a client · First conversation · Tools · Security and privacy · Development

Setup

You need access to Althea and uv. Install Althea MCP from PyPI, then sign in with an emailed verification code:

bash
uv tool install althea-mcpalthea-mcp setup

If the install succeeds but the command is not found, run uv tool update-shell and open a new terminal.

Run setup yourself in an interactive terminal. Enter your email and verification code there, not in an AI chat.

text
Connect your personal Althea-----------------------------Email: [email protected]A verification code was sent to [email protected].Verification code:
Althea MCP is ready.Credentials saved to ~/.config/althea-mcp/credentials.json

Setup follows the same account journey as the Althea web app:

  • Existing accounts receive a verification code by email.
  • Eligible new accounts are asked for a name, then receive a verification code.
  • Accounts that still need access are sent to the Althea application. Complete it, then run setup again.

The installed server starts without fetching code on every launch. Its tools still need a network connection to Althea. Upgrade the package later with:

bash
uv tool upgrade althea-mcp

Connect an MCP client

Complete setup once, then add the local stdio server. Give each client a different thread key.

[!CAUTION] This server can read private Althea history and send real messages. Register it only in clients and projects you trust.

Codex

bash
codex mcp add althea \  --env ALTHEA_THREAD_KEY=codex \  -- althea-mcpcodex mcp list

codex mcp add writes to your user configuration. Equivalent ~/.codex/config.toml:

toml
[mcp_servers.althea]command = "althea-mcp"
[mcp_servers.althea.env]ALTHEA_THREAD_KEY = "codex"

Claude Code

bash
claude mcp add althea \  -e ALTHEA_THREAD_KEY=claude-code \  -- althea-mcpclaude mcp list

That command uses Claude Code's project-local scope. Add --scope user immediately before althea only if you want the server available in every project you open.

A user-wide manual entry under the top-level mcpServers object in ~/.claude.json looks like this:

json
{  "mcpServers": {    "althea": {      "type": "stdio",      "command": "althea-mcp",      "env": {        "ALTHEA_THREAD_KEY": "claude-code"      }    }  }}

Claude Desktop and other local clients

Find the installed command:

bash
command -v althea-mcp

On Windows PowerShell:

powershell
(Get-Command althea-mcp).Source

GUI applications sometimes receive a smaller PATH than your terminal. If althea-mcp is not found, use the absolute path returned above:

json
{  "mcpServers": {    "althea": {      "command": "/absolute/path/to/althea-mcp",      "env": {        "ALTHEA_THREAD_KEY": "claude-desktop"      }    }  }}

Restart the client after changing its MCP configuration.

Start a conversation

Try one of these prompts in your MCP client:

text
Ask my Althea whether anyone in the researcher network has worked on thisfailure mode. Share only the sanitized summary below:[summary]
text
Send this context to my Althea without waiting for a reply:The latest experiment rules out the data-loader hypothesis. The remainingfailure starts after gradient accumulation.
text
Check whether my Althea has replied in the MCP thread.

Messages continue the configured thread. They are real messages to your personal Althea and may cause her to begin work.

Tools

ToolWhat it does
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.
send_message_to_althea(message)Sends a message immediately and returns a receipt without waiting. Use it for context, notes, and longer requests.
get_althea_messages(sender=None, limit=10)Returns 1 to 100 recent messages in chronological order. Optionally filter by user, assistant, or system.
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.
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.

The two send tools are marked as state-changing. Conversation search and message retrieval are read-only. The current tool surface is text-only. It does not expose attachments or other Althea artifacts.

How it works

text
Codex / Claude Code / another coding agent                    │ local stdio                    ▼               Althea MCP                    │ HTTPS                    ▼              your Althea                    │                    ├── your profile and long-term research memory                    ├── a persisted conversation for this thread key                    └── a consent-first network of verified ML researchers

Althea MCP is a small public adapter. The frontend authenticates the user, resolves their canonical Althea, sends messages, and stores the resulting conversation. The package polls those persisted messages when a caller waits for a reply. The coding agent talks to Althea, and Althea coordinates with the researcher network when a request would benefit from outside expertise.

Sign-in and sessions

Setup creates a normal Althea usage session:

  • The access session lasts 7 days.
  • Its rotating refresh-token family lasts 14 days from sign-in.
  • Access tokens refresh automatically before expiry.
  • A cross-process lock lets several local MCP clients share the credential file without racing refresh-token rotation.
  • When the session expires or is revoked, run althea-mcp setup again in a separate terminal. Running MCP processes reload the replacement credentials.
  • Signing in again rotates credentials only. It does not replace conversation history when the Althea account and ALTHEA_THREAD_KEY stay the same.

Credentials are stored as plaintext JSON at ~/.config/althea-mcp/credentials.json. On operating systems that support Unix file modes, the credential file is set to 0600. A parent directory created by Althea MCP is requested as 0700; check the permissions yourself when using a pre-existing custom directory.

Security and privacy

  • Messages sent through these tools are persisted in your Althea account, like messages from Althea's other channels.
  • The local stdio process sends messages and credentials to Althea over HTTPS. Even with local transport, conversation data leaves your machine.
  • The connected MCP host and model can see tool arguments and replies. They may retain that data under their own privacy and retention policies.
  • When Althea asks the researcher network for help, she requests consent before sharing information drawn from a private conversation.
  • The package sends access credentials only to the Althea origin they were issued for. Changing ALTHEA_APP_URL requires a new setup.
  • The refresh token is sent only to the session rotation endpoint.
  • Email verification codes and the credential file are secrets. Never paste them into an AI chat, terminal transcript, issue, or pull request.
  • To remove the local session, close MCP clients and delete the credential file. This forgets the session on that machine. Contact Tiptree if a copied session must also be revoked.

Please report vulnerabilities using the security policy.

Configuration

Most users only need althea-mcp setup and a client-specific thread key.

Environment variableDefaultPurpose
ALTHEA_APP_URLhttps://althea.tiptreesystems.comAlthea API origin. Saved credentials are bound to it. Plain HTTP is accepted only for loopback development.
ALTHEA_PUBLIC_SITE_URLhttps://tiptreesystems.comBase URL for terms, privacy, and access requests. Dev Althea selects https://dev.tiptreesystems.com automatically.
ALTHEA_THREAD_KEYmcpStable conversation identifier. Use 1 to 128 letters, digits, dots, underscores, colons, or hyphens, starting with a letter or digit.
ALTHEA_MCP_CREDENTIALS_FILE~/.config/althea-mcp/credentials.jsonOverride the local credential path.
ALTHEA_MCP_HTTP_TIMEOUT60HTTP timeout in seconds.
ALTHEA_MCP_POLL_INTERVAL2Delay between response polls in seconds.
ALTHEA_MCP_POLL_TIMEOUT120Maximum wait for ask_althea in seconds.
ALTHEA_MCP_LOG_LEVELWARNINGPython log level.

Setup also accepts --credentials-file to override the credential path and --no-browser to print an access-request URL without opening it.

Troubleshooting

Althea MCP is not configured

Run althea-mcp setup in a terminal, then restart the MCP client.

Your Althea MCP sign-in has expired or was revoked

Run setup again. The refresh-token family has a 14-day absolute lifetime.

Saved credentials are bound to another URL

Run setup with the same origin the MCP client will use:

bash
althea-mcp setup --app-url https://althea.example

Then set the matching ALTHEA_APP_URL in the client configuration.

ask_althea timed out

Althea may still be working. Call get_althea_messages after a short wait.

The client cannot find althea-mcp

Run command -v althea-mcp in a terminal and use that absolute path in the client configuration.

Two clients are sharing a conversation

Assign a distinct ALTHEA_THREAD_KEY to each client and restart them.

Local development

bash
git clone https://github.com/tiptreesystems/althea-mcp.gitcd althea-mcpuv sync --locked --extra devuv run pytest -quv run ruff check althea_mcp testsuv run ruff format --check .uv builduvx twine check dist/*

Run setup against a local frontend:

bash
uv run althea-mcp setup --app-url http://localhost:8080

Running althea-mcp with no subcommand starts the stdio server. The explicit equivalent is althea-mcp serve.

Contributing

Bug reports and focused pull requests are welcome. Read the contribution guide before opening one. Remove all email addresses, messages, OTPs, and credentials from logs and fixtures.

License

MIT © Tiptree Advanced Systems Corporation.

Source: README.md at commit 1990a62

Tools

0
SourceWeft started this package once in an isolated sandbox, without credentials, to list its tools. That failed: the server did not start.

Version history

3
  1. v0.2.1LatestOct 22, 2026
  2. v0.2.0Oct 19, 2026
  3. v0.1.0Sep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts