Hypha MCP server
Commit Nov 13, 2026Build governed, durable LLM agent applications with a TypeScript Agent Core and Production Harness.
Also known as CodeSoul-co/Hypha
- Stars
- 452
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 13, 2026
- License
- Apache-2.0
What is Hypha MCP?
Hypha builds governed, durable LLM agent applications with a TypeScript Agent Core and Production Harness.
Summary generated from the project's README
About Hypha MCP server
Building agent products that stay bounded and auditable is the job Hypha takes on. It is an open-source TypeScript framework split into an Agent Core, which handles reasoning and ReAct, planning, tool selection, Memory access, and model and context orchestration, and a Production Harness, which turns those decisions into event-backed execution with FSM control, policy and approval, checkpoints, recovery, replay, and audit. Product behavior is declared in a DomainPack rather than hard-coded, so coding, finance, legal, or research agents can share one runtime.
The current public release is v1.0.1, shipped as 15 packages named @codesoul-co/hypha-*, with a versioned user guide covering an API atlas per package, custom FSM control, and a composition example. Writes to tools, MCP, Memory, files, execution, and external systems flow through policy, trace, cancellation, deadline, idempotency, and harness boundaries, and a cache hit cannot authorize a side effect, advance the FSM, or replace Event and Artifact evidence.
Cache is a control plane with separate layers: Serving, Thinking, Work, Tool and Execution, Memory and Context, and Prefix and KV, each with its own validity boundary. Typed cache trees such as PlanTree, ToolTree, and RecoveryTree reuse validated work under a rule of reuse without authority. A Tau3 comparison on main@ef33263 with deepseek-v4-flash over 385 tasks scored 0.636 against a 0.626 direct baseline.
What you can do with it
- 1Declare a domain agent packAsk the agent to define a DomainPack that compiles tasks, workflows, capabilities, prompts, Memory, policy, evaluation, and output contracts into the shared runtime.
- 2Recover a durable agent runHave the client resume an interrupted Run from its checkpoint and replay the Event history to rebuild the projected state.
- 3Audit governed tool writesTrace every tool, MCP, Memory, file, and execution write through policy, deadline, and idempotency boundaries before it lands.
- 4Invalidate a stale cache branchInsert new leaves in a typed cache tree and invalidate only the stale ones without rebuilding unrelated branches.
- 5Compare against a direct baselineRun the Tau3 benchmark suite with the harness enabled and compare task success against plain model calls.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
HYPHA_LLM_DEFAULT_MODELHYPHA_LLM_DEFAULT_PROVIDERHYPHA_OWNER_EMAILHYPHA_OWNER_PASSWORDJWT_SECRETNODE_ENVOPENAI_API_KEY
Automated checks
Ran Nov 13, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablecodesoul-co/hypha is public and reachablegithub.com/codesoul-co/hypha ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-09-04github.com/codesoul-co/hypha ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubCurrent public release: v1.0.1, with 15 aligned packages named
@codesoul-co/hypha-*. The versioned user guide includes an API atlas for every package, custom FSM control, and a complete composition example.
What is hypha?
hypha is an open-source TypeScript framework built around two cooperating layers: an Agent Core and a Production Harness. The Agent Core handles reasoning/ReAct, planning, tool selection, Memory access, and model/context orchestration; the Production Harness turns those decisions into bounded, event-backed execution with FSM control, policy/approval, checkpoints, recovery, replay, and audit.
Product-specific behavior is declared through a DomainPack, not hard-coded into the runtime. A
DomainPack compiles tasks, workflows, capabilities, prompts, Memory, policy, evaluation, and output
contracts into the shared Core + Harness. A cross-cutting Cache & Reuse Plane then reuses
validated work across reasoning, tools, Memory, execution, and inference while remaining a disposable
projection: cache state can accelerate execution, but it can never become authority or replace Event,
Artifact, receipt, or checkpoint evidence.
Architecture at a glance
| Layer | Primary responsibility |
|---|---|
| Agent Core | Reasoning/ReAct, planning, tool selection, Memory access, model and context orchestration. |
| Production Harness | FSM execution, Event/checkpoint control, policy/approval, continuation, recovery, audit, and replay. |
| DomainPack | Declares the product-specific task, workflow, capability, Memory, Skill, Prompt, Policy, evaluation, and output contracts compiled into the shared runtime. |
| Cache & Reuse Plane | Reuses validated model work, reasoning structures, tool/execution results, Memory/context projections, and prefix/KV state without becoming a source of truth or authority. |
This separation is what lets the same runtime support very different agent products. A coding agent, finance agent, legal agent, or research agent can share the same Core + Harness while changing the DomainPack, capability bindings, policies, evaluation contracts, and domain-specific state.
Cache management and typed cache trees
Cache is a first-class control plane in hypha, not a single response-cache feature. The system distinguishes several reuse layers because an exact LLM response, a reasoning subgraph, a tool result, a Memory projection, and a KV prefix have different validity and invalidation requirements.
| Cache layer | Reusable unit | Typical validity boundary |
|---|---|---|
| Serving Cache | Exact normalized model response | Model/provider identity, normalized request, scope, TTL, and response validity. |
| Thinking Cache | Reasoning node, path, or reusable subgraph | Model/provider, reasoning strategy/version, prompt blocks, tool schema, inference parameters, and scope. |
| WorkCache | Event-derived typed agent work | Source-event provenance, dependency/revision closure, scope, validity state, and future demand. |
| Tool / Execution Cache | Eligible read-only tool results or deterministic execution results | Capability revision, Policy, external-state evidence, workspace/environment snapshot, idempotency, and scope. |
| Memory / Context Cache | Memory search and assembled context projections | Memory scope, mutation generation, source revision, provenance, and context policy. |
| Prefix / KV Cache | Prompt-prefix blocks, provider prefixes, or backend KV segments | Model/backend, Agent/Session/Domain scope, prompt dependencies, and prefix/KV revision. |
A cache tree uses a typed root to partition reusable artifacts, compact parent nodes to route lookups by hash prefix, and full logical keys at the leaves. New leaves can be inserted without rebuilding unrelated branches, while stale leaves can be invalidated locally; the physical tree is therefore a lookup structure, while Event and Artifact evidence remain the source of truth.
WorkCache extends that lookup pattern into semantic cache trees for agent execution:
| Semantic tree | What it reuses |
|---|---|
PlanTree |
Plans, plan branches, and reusable planning artifacts. |
ComputationTree |
Reasoning/computation nodes and derived work; also the natural backing plane for Thinking Cache. |
ToolTree |
Eligible tool-call results and their provenance/validity metadata. |
ObservationTree |
Reusable observations tied to source evidence and scope. |
VerificationTree |
Verification, checking, and output-validation work. |
MemoryTree |
Memory-derived projections whose validity follows Memory mutation generations and scope. |
RecoveryTree |
Recovery knowledge keyed by failure context and relevant runtime revisions; hits are advisory and must be revalidated. |
PromptPrefixTree |
Stable prompt blocks and prefix materialization used by provider/backend prefix reuse. |
The central invariant is reuse without authority. A hit may avoid recomputation, but it cannot authorize a Tool, skip Policy or Approval, fabricate a receipt, advance the FSM, or replace Event and Artifact evidence. Cache lookup, validation, invalidation, and bypass are therefore part of runtime control rather than hidden implementation details.
Cache diagnostics across benchmarks
Tau3 benchmark results
The latest three-way comparison was run against Hypha main@ef33263 with one trial per task
(385 tasks total). The base model was deepseek-v4-flash. Hypha is the framework result and
Direct is the direct model-call baseline. Neither arm reported a system error.
| Benchmark | Tasks | Hypha | Direct |
|---|---|---|---|
| Mock | 10 | 0.800 (8/10) | 0.800 (8/10) |
| Airline | 50 | 0.880 (44/50) | 0.900 (45/50) |
| Retail | 114 | 0.912 (104/114) | 0.895 (102/114) |
| Telecom | 114 | 0.605 (69/114) | 0.588 (67/114) |
| Banking knowledge | 97 | 0.206 (20/97) | 0.196 (19/97) |
| Total | 385 | 0.636 (245/385) | 0.626 (241/385) |
Product model
| Concept | Responsibility |
|---|---|
DomainPack |
Declares tasks, workflows, output contracts, skills, tools, MCP, memory, context, policy, evaluation, regression, and deployment references. |
Agent |
Selects model aliases and receives the capability references compiled from a DomainPack. |
Session |
Holds user and product context. A Session references a DomainPack and optional Session profile. |
Run |
Represents one durable execution under a Session. |
Event |
Records source-of-truth facts from which state, replay, audit, and regression views are projected. |
Artifact |
Stores content-addressed inputs, outputs, checkpoints, and execution evidence. |
The canonical execution path is:
DomainPack
-> validated bindings and dependency snapshot
-> framework-owned Harness FSM
-> bounded ReAct quantum and Domain pipeline evidence
-> governed Tool / MCP / Memory / Execution activity
-> Event + receipt + Artifact evidence
-> projection, continuation, recovery, replay, and evaluation
No cache hit or provider response can authorize a side effect, advance the FSM, or replace Event and Artifact evidence. Tool, MCP, Memory, file, execution, and external writes pass through policy, trace, cancellation, deadline, idempotency, and harness boundaries.
Included capabilities
| Area | Included runtime capability |
|---|---|
| Runtime | ReAct + FSM, durable session commands, bounded continuation, timers, leases, fencing, cancellation, recovery workers, human review, replay, audit, and regression projections. |
| Domain | YAML/JSON/TypeScript Domain Packs, runtime validation, overlays, registry, deterministic compiler, dependency snapshots, and Agent patches. |
| Memory | Hypha Native Memory, local Native Lite, self-hosted Mem0 OSS, Mem0 Platform, and Vertex AI Memory Bank adapters behind one governed contract. |
| Tools and MCP | Local, HTTP, plugin, mock, and MCP adapters through one governed invocation path with capability snapshots and drift control. |
| Skills and prompts | Built-in, filesystem, package, and signed remote Skill registries; progressive loading; versioned prompt references and templates. |
| Execution | Provider-neutral Workspace, Sandbox, Command, Artifact, Store, lease, recovery, and cache contracts with local-process, Docker, remote HTTP, SQLite, PostgreSQL, local-file, and S3-compatible adapters. |
| Cache | Serving Cache, event-derived WorkCache, Thinking Cache, typed semantic cache trees, capability-result caches, Memory/context projections, Prefix/KV reuse, scoped validity, and invalidation. |
| Surfaces | Express API server and an example CLI that consume the same framework runtime. |
Quick start
Requirements
- Node.js 22 or newer
- npm
- MongoDB and Redis for the bundled API server
- At least one configured model provider or a reachable local model endpoint
1. Install the workspace
git clone https://github.com/CodeSoul-co/Hypha.git
cd Hypha
npm ci
cp .env.example .env
Keep product configuration out of tracked templates. Set HYPHA_CONFIG_PATH to a user-owned YAML
overlay; see Upgrading for the conflict-free update layout.
For a disposable local MongoDB and Redis environment, you may use containers:
docker run -d --name hypha-mongodb -p 27017:27017 mongo:8
docker run -d --name hypha-redis -p 6379:6379 redis:7-alpine
You can instead set MONGODB_URI and REDIS_URL to self-hosted or managed services.
2. Configure identity and a model provider
Edit .env. Keep credentials out of config.yaml and source control.
HYPHA_OWNER_EMAIL=owner@example.com
HYPHA_OWNER_PASSWORD=replace-with-a-private-password
JWT_SECRET=replace-with-at-least-32-random-characters
HYPHA_LLM_DEFAULT_PROVIDER=openai
HYPHA_LLM_DEFAULT_MODEL=gpt-4o-mini
OPENAI_API_KEY=your-provider-key
The default deployment mode is single-user. Registration remains disabled and the configured owner is created during startup. Internal data access still retains user, Session, Run, Workspace, and tenant boundaries.
3. Start and verify the server
npm run dev
In another terminal:
curl -fsS http://127.0.0.1:3000/api/v1/health
curl -fsS http://127.0.0.1:3000/api/v1/ready
/health is process liveness. /ready is the traffic gate: it returns a failure status until
storage, the selected model provider, Memory, the canonical Runtime graph, and required workers are
ready. The route index is available at http://127.0.0.1:3000/api/v1/docs.
4. Use the CLI
npm run cli -- login --email owner@example.com
npm run cli -- chat "Explain the active runtime" --stream
npm run cli -- tools
npm run cli -- skills
npm run cli -- workflows
The CLI stores its endpoint configuration and JWT under ~/.hypha by default. Set
HYPHA_BASE_URL and HYPHA_HOME to use another server or an isolated client profile.
Develop an agent with a DomainPack
Domain Packs are the supported product-integration boundary. Product-specific tasks, prompts,
workflows, rules, and capability selections belong in a Domain Pack or product application—not in
@codesoul-co/hypha-core, @codesoul-co/hypha-kernel, or the generic Runtime.
For an application that consumes a versioned npm release, including separate Prompt, Skill, Tool,
policy, contract test, and HTTP Run submission, see the
release-agent example.
1. Declare the domain
Start from configs/domain-packs/minimal.domain.yaml.
A production Domain Pack normally defines:
| Declaration | What it controls |
|---|---|
taskSchemas |
Accepted task types, input schemas, output-contract references, and default workflows. |
outputContracts |
Machine-verifiable final output schemas. |
sessionProfiles |
Default metadata and Memory, Context, Reasoning, Tool, MCP, Skill, and Policy profile references. |
workflows |
Product stages, guards, retry/timeout intent, human review, state-scoped capabilities, and topology evidence. ReAct Runs retain the protected Harness FSM; custom FSM Runs may use a separately validated application topology. |
tools, toolProfiles |
Stable Tool contracts and the profiles allowed to bind them to executable adapters. |
mcpProfiles |
Server references, capability import rules, trust policy, and version pinning. |
memoryProfiles, contextProfiles |
Memory selection, retrieval/write policy, context sources, provenance, and token budgets. |
allowedSkills, skillPolicies |
Which Skills an Agent may load and which tools or policies each Skill may use. |
allowedPromptRefs, defaultPromptRefs |
Versioned prompt templates that application composition must resolve. |
policies, businessRules |
Permission, approval, precondition, postcondition, and output constraints. |
evaluationProfiles, regressionCases |
Event-derived acceptance and regression definitions. |
Keep provider URLs, bearer tokens, API keys, and deployment secrets out of the Domain Pack. It should select stable profile references; the trusted application composition resolves those references to live providers.
2. Load, validate, and compile
import {
applyDomainAgentPatch,
compileDomainPackToHarnessedSystem,
DomainPackRegistry,
LocalDomainPackLoader,
} from '@codesoul-co/hypha-domain';
const registry = new DomainPackRegistry();
await new LocalDomainPackLoader({
directories: ['configs/domain-packs'],
}).loadInto(registry);
const domainPack = registry.get('domain.minimal', '0.0.0');
if (!domainPack) throw new Error('DomainPack not found');
const compiled = compileDomainPackToHarnessedSystem(domainPack, {
agentRef: { id: 'agent.default', version: '1.0.0' },
taskSchemaId: 'task.minimal',
workflowId: 'workflow.minimal',
sessionProfileId: 'session.local',
memoryProfileId: 'memory.local',
});
const agent = applyDomainAgentPatch(
{
id: 'agent.default',
version: '1.0.0',
name: 'Default Agent',
modelAlias: 'default-chat',
},
compiled.agentPatch
);
The compiler validates internal references and produces all data needed by application composition:
| Compiler output | Integration use |
|---|---|
fsmProcess |
Register the canonical, framework-owned Harness FSMProcessSpec. |
harnessedSystem |
Bind Agent, FSM, policy, trace, Memory, MCP, Context, Tool, Skill, evaluation, and output refs. |
agentPatch |
Apply resolved prompt, Skill, Tool, Memory, Context, Reasoning, and Policy references to the Agent. |
bindings |
Register only the selected concrete capabilities and state-level allowlists. |
sessionInitialization |
Create Session metadata and default profile references. |
dependencySnapshot |
Persist the complete versioned dependency closure used for replay and cache validity. |
processHash and audit |
Prove the compiler input and workflow identity associated with a Run. |
Hypha MCP questions
What is Hypha?
Hypha is an open-source TypeScript framework combining an Agent Core with a Production Harness for governed, durable agent applications.
What is a DomainPack in Hypha?
A DomainPack declares product-specific tasks, workflows, capabilities, prompts, memory, policy, and output contracts compiled into the shared runtime.
Does Hypha support MCP tools?
Yes, tool, MCP, memory, file, and execution activity pass through policy, trace, and harness boundaries.
Can cache hits authorize actions in Hypha?
No, cache hits are advisory and cannot authorize side effects, advance the FSM, or replace event and artifact evidence.