Integrations

This page explains how to plug Hypercontext into other tools and assistants. The current split is:

• python -m hypercontext mcp launches the stdio MCP daemon for Claude Desktop, Claude Code, Codex, and other assistants that speak MCP over stdin/stdout.
• python -m hypercontext serve launches the HTTP MCP server for the browser dashboard and local HTTP integrations.
• hypercontext-node-sdk is the TypeScript SDK for Node.js applications.

Choose Your Install Path

Install path	Best for	Typical entry points
Python package installed	Using Hypercontext from another project with the installed package	python -m hypercontext ...
Npm package installed	Node.js applications and TypeScript agents	import { ... } from 'hypercontext-node-sdk'

1. Python Package Installed

If you installed Hypercontext from PyPI:

pip install hypercontext

Then use the CLI from any project directory:

python -m hypercontext version
python -m hypercontext mcp --workdir /path/to/project
python -m hypercontext tui --workdir /path/to/project
python -m hypercontext serve --port 8080 --workdir /path/to/project

This is the cleanest route if you want Hypercontext on a machine where the installed package is all you need.

2. Npm Package Installed

If you are building a Node.js or TypeScript app, install the SDK:

npm install hypercontext-node-sdk

Use it from application code:

import {
  ContextCompressor,
  StructuredOutputParser,
  EnhancedToolRegistry,
  LoggingMiddleware,
  TaskAgent,
} from "hypercontext-node-sdk";

const compressor = new ContextCompressor();
const parser = new StructuredOutputParser();

const registry = new EnhancedToolRegistry();
registry.use(new LoggingMiddleware());
registry.registerTool(
  {
    name: "echo",
    description: "Echo a payload back",
    parameters: { type: "object" },
  },
  async (args) => args,
);

const agent = new TaskAgent({ name: "demo", maxTokens: 1024 });
console.log(agent.forward({ prompt: "hello" }).prediction);
console.log(parser.parseFirst('Result: {"status":"ok"}'));

Use the npm package when:

• your app runtime is Node.js
• you want to call Hypercontext from TypeScript directly
• you are building tooling around the SDK rather than the Python CLI

The npm package is an SDK. It does not replace the Python CLI commands such as run, tui, mcp, or serve.

3. Claude Desktop

Claude Desktop usually wants a local stdio MCP server. Hypercontext now ships one directly, so you do not need a bridge for the standard desktop workflow.

Python Package Installed

If Hypercontext is installed from PyPI, use the installed python entry point:

{
  "mcpServers": {
    "hypercontext": {
      "command": "python",
      "args": ["-m", "hypercontext", "mcp", "--workdir", "/path/to/project"]
    }
  }
}

What You Get

The stdio daemon exposes the same core tool/resource surface to desktop agents:

• compress
• retrieve
• evaluate
• archive_list
• archive_show
• sandbox_run
• evolution_start
• mutation_apply
• benchmark_run
• archive, lineage, config, and evolution resources

If you still need the HTTP path for another UI or integration, use python -m hypercontext serve --port 8080 --workdir /path/to/project.

4. Codex And Other Terminal Agents

Codex-style terminal workflows work best when you call Hypercontext directly from the shell:

python -m hypercontext providers
python -m hypercontext mcp --workdir /path/to/project
python -m hypercontext run --generations 5 --output-dir ./runs/demo --workdir /path/to/project
python -m hypercontext evaluate /path/to/project --domains memory --workdir /path/to/project
python -m hypercontext tui --workdir /path/to/project

Use this mode when you want:

• a local agent to inspect a repo
• to run the evolutionary loop against a project directory
• to keep the working directory explicit instead of cd-ing manually

5. Practical Examples

Example: Claude Desktop With A Local Project

1. Install Hypercontext.
2. Make sure your provider settings are in .env or exported in the shell.
3. Register the python -m hypercontext mcp --workdir /path/to/project command in the Claude Desktop MCP configuration.
4. Use compress, retrieve, sandbox_run, and archive_show from Claude Desktop when you need Hypercontext features.

Example: Codex On A Local Repo

1. Install Hypercontext with Python, or use the Python environment that already has it installed.
2. Run python -m hypercontext mcp --workdir /path/to/project if your terminal agent expects an MCP daemon.
3. Use python -m hypercontext tui --workdir /path/to/project for the shell dashboard.
4. Use python -m hypercontext run --generations 5 --workdir /path/to/project when you want the full evolutionary loop.

Example: Node.js App Using The SDK

1. Install hypercontext-node-sdk.
2. Import the SDK in your TypeScript app.
3. Keep your provider credentials in environment variables.
4. Use the SDK for agent logic, and the Python CLI only when you need the MCP daemon or HTTP server.

6. Which Path Should I Pick?

• Pick the Python package path if you want the CLI and servers from the installed package.
• Pick the npm package if you are building a Node.js application around the SDK.
• Pick Claude Desktop with mcp if you want a native stdio MCP daemon.
• Pick serve if you want the HTTP server for the browser UI or a custom web integration.
• Pick Codex plus the CLI if you want the fastest terminal-native workflow.