Janux MCP server
Commit Oct 17, 2026A fullstack framework that automatically generates MCP tools, resources, and UI views from a single component definition.
Also known as aralroca/Janux
- Stars
- 13
- Tools
- β
- Downloads, 30 days
- β
- Latest version
- β
- Last commit
- Oct 17, 2026
- License
- MIT
What is Janux MCP?
Janux is a fullstack framework that automatically generates MCP tools, resources, and UI views from a single component definition.
Summary generated from the project's README
About Janux MCP server
Developers building for the Agentic Web can use Janux to create applications that serve both human users and AI agents simultaneously. By defining a single component, the framework automatically generates a live UI view, typed MCP tools, and agent-readable resources. This approach ensures that the logic used by a human clicking a button is identical to the logic an agent uses when calling a tool, preventing the common issue of tool drift where agent capabilities fall out of sync with the actual application code.
To use Janux, developers can initialize a project using Bun and add specific packages like @janux/server or @janux/agent to existing workspaces. The framework supports various deployment targets including Node 24+, Vercel, or static exports. It provides a stateless MCP server at a specific endpoint, allowing clients like Claude or Cursor to connect via HTTP. The system includes built-in guard mechanisms, such as the confirm setting, which allows humans to approve agent proposals directly through the UI.
What you can do with it
- 1Synchronize UI and agent toolsA developer can define a single component to ensure that human interactions and agent tool calls follow the exact same validation and audit pipeline.
- 2Implement human-in-the-loop approvalsYou can require a person to manually approve an agent's action by using a specific guard configuration.
- 3Connect AI clients to web appsYou can add your application to an MCP client like Claude using a simple HTTP transport command.
- 4Automate agentic testingDevelopers can use built-in tools to replay scripted tasks and verify that agent-reachable tools have proper descriptions.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 14, 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 reachablearalroca/janux is public and reachablegithub.com/aralroca/janux βPass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html βPass
- Commit or release in the last yearLast commit or release 2026-10-17github.com/aralroca/janux β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 GitHub[!WARNING] Janux is currently under active development. This repository is public to enable collaboration and transparency, but it has not been officially announced yet. Expect breaking changes, incomplete documentation, and unfinished features until the first public release.
Why Janux
The web is growing a second audience. People still click, but agents now read, plan and act on the same pages β through MCP clients, through browser agents, through copilots embedded in your own product. The Agentic Web is the web both of them can operate, and it is being standardized in the open: MCP for tools over HTTP, WebMCP for tools in the browser, llms.txt for discovery, Web Bot Auth for identity.
Today, making an app agent-operable means building it twice. The UI already holds the logic β the validation, the permissions, the business rules β and then a second, hand-written integration re-declares a fraction of it as tools. Two artifacts, one source of truth, and the gap between them grows with every sprint. Tools drift, guardrails are ad-hoc, and nobody can say exactly what an agent is allowed to do.
Janux removes the second artifact. A component is simultaneously a view, an agent-readable resource and a set of typed tools β one definition, projected three ways by the framework. A human click and an agent tool call enter the same pipeline: guard check β schema validation β run() β audit entry. The contract can't rot, because it is generated from the code that renders.
Named after Janus, the two-faced Roman god of doorways: one face toward the human, one toward the agent, one threshold. Designed in RFC 0001.
Table of Contents
- Install
- Quick start
- One component, three projections
- Two agent surfaces, zero integration
- Humans stay in the loop
- Highlights
- How it works
- Performance
- Packages
- Documentation
- Benchmarks
- Templates
- Examples
- Develop
- Contributing
- Releases
- License
Install
bunx create-janux my-app
cd my-app && bun install && bun run dev
Requires Bun β₯ 1.3 for the dev server and the build. Production is a choice: Bun, Node 24+ via @janux/node, Vercel, or a static export β same app, one adapter.
Or add the pieces to an existing workspace:
bun add janux @janux/server @janux/agent @janux/cli
Quick start
import { component, intent, schema, str, int, money, list } from 'janux';
import { pay } from './pay.api';
// UI component + 2 WebMCP tools (intents), grouped together for maintainability
export const Cart = component({
name: 'cart',
description: 'Shopping cart with line items.',
state: schema({ items: list({ productId: str(), qty: int().min(1), unitPrice: money() }) }),
derived: { total: (s) => s.items.reduce((a, i) => a + i.qty * i.unitPrice, 0) },
intents: {
addItem: intent({
description: 'Add a product to the cart',
input: schema({ productId: str(), qty: int().default(1), unitPrice: money().default(0) }),
run: ({ state, input }) => state.items.push(input),
}),
checkout: intent({ description: 'Pay for the cart', guard: 'confirm', run: ({ state }) => pay({ items: state.items }) }),
},
view: ({ state, derived, intents }) => (
<section>
<ul>
{state.items.map((i) => (
<li key={i.productId}>{i.productId} Γ {i.qty}</li>
))}
</ul>
<button onClick={intents.checkout}>Pay ({derived.total}Β’)</button>
</section>
),
});
You wrote a shopping cart. You also shipped an agent surface β generated, no second file:
{
"resources": ["ui://cart"],
"tools": [
{ "name": "cart.addItem", "description": "Add a product to the cart", "guard": "auto" },
{ "name": "cart.checkout", "description": "Pay for the cart", "guard": "confirm" }
]
}
One component, three projections
| Projection | For | What it is |
|---|---|---|
| View | humans | server-rendered HTML that resumes on first interaction |
| Resource | agents | ui://cart β typed JSON state, readable and subscribable |
| Tools | both | cart.addItem (auto), cart.checkout (confirm β a human approves) |
They cannot drift: there is one definition, and the framework derives the other two. A human click and an agent tool call run the exact same pipeline β guard check β schema validation β run() β audit entry.
Two agent surfaces, zero integration
Every Janux app speaks the Agentic Web's protocols out of the box. You declare no tools twice, and you write no adapters.
| Standard | What Janux does with it |
|---|---|
| MCP β tools over HTTP | A real, stateless MCP server at /_janux/mcp, generated from your api() functions. Dual-era: negotiates 2026-07-28 and 2025-06-18. |
| A2A β agent to agent | A derived /.well-known/agent-card.json and a JSON-RPC endpoint at /_janux/a2a, over the same pipeline and the same guards as MCP β so an agent that arrives by A2A holds no authority an MCP client would be refused. |
| WebMCP β tools in the browser | Every mounted intent is registered with document.modelContext the moment its island mounts, so browser agents and the DevTools panel see it. Polyfilled where the API is missing. |
llms.txt β discovery |
Opt-in site index at /llms.txt (dynamic routes expanded via staticParams), plus a Markdown projection of every page by appending .md. |
| Web Bot Auth (RFC 9421) | Signed agent identity, verified per request under an observe or require policy. |
| Human approval | guard: 'confirm' reaches MCP clients as annotations.requiresApproval, arrives over A2A as TASK_STATE_INPUT_REQUIRED, and parks agent calls as Proposals whichever door they came through. |
Pointing Claude, Cursor or any MCP client at your app is a URL, not an integration project:
claude mcp add --transport http my-app https://your.app/_janux/mcp
Humans stay in the loop
Guards are a language feature, not a convention. Every intent and every api() declares who may call it:
autoβ agents call it directly.confirmβ a human click runs it; an agent call parks as a Proposal that a person approves or rejects on the real UI, executing exactly once.forbiddenβ never exposed as a tool. The agent falls back to the DOM, under the same permissions as a user.
Every invocation records its origin (human / agent) in an audit trail, and janux verify fails the build if an agent-reachable tool ships without a description. See examples/human-in-the-loop in the table below.
Highlights
- π§Ώ One definition, three projections. The mounted tree is the MCP tree β UI and agent surface cannot drift.
- πͺΆ 0 KB JS static pages. Components without state compile to plain HTML; a page with no islands ships no
<script>at all. - β‘ Structural resumability. State is schema-typed JSON, behavior is named β the client resumes from snapshots with no hydration replay and no closure serialization. Zero component code runs until first interaction (asserted in the test suite).
- π
api()= endpoint + stub + tool. A server function is at once a validated HTTP endpoint, a ~100-byte typed client stub (SWC transform) and an agent tool. - π€ Zero-config copilot.
JANUX_MODELor one provider API key (Anthropic, OpenAI, Google or OpenRouter) is all it takes. Every app ships the agent endpoint, the manifest and the gui-agent bridge (window.janux). - πΊοΈ App-wide agent control. Every turn advertises built-in client tools (
ui_navigate,ui_get_view_context,ui_read_page,ui_click,ui_fill,ui_wait_settled) plus the full route map β andui_callsturns resume with their results (act β observe β continue), so navigate-then-act works in one turn. - βοΈ Foreign-UI interop.
foreign()mounts React components unchanged β real embedded roots, tracked props, callbacksβintents β surviving SPA navigation. - π§ Observable quiescence.
await janux.settled()β thesleep(500)idiom dies here. - π§ͺ CI for the agent surface.
janux verifygates undescribed tools;janux evalreplays scripted agent tasks β including real human-approval steps β against a live app.
How it works
Browser ββ janux core (signals, resume, morph, delegation, window.janux bridge)
β HTML + state snapshots β RPC β agent turns
Server ββ @janux/server (SSR, api(), manifest, proposals)
βββ @janux/agent (model resolution, provider loop: api.* server-side, ui_calls β bridge)
- SSR: sources load server-side; islands arrive with real content plus a JSON state snapshot.
- Resume:
boot()indexes islands, installs two delegated listeners, and mounts an island only on first interaction or agent call β from the snapshot, morphing the SSR DOM in place. - Agents:
GET /_janux/manifest?path=/shopfor discovery;POST /_janux/api/*for server tools;window.janux.call()for UI tools;POST /_janux/approvefor proposals. - Static export:
output: "static"prerenders every page intodist/clientβ deploy docs and marketing sites to any static host, agent face included, no server.
Configure the copilot model
Zero config β first match wins:
defineAgent({ model: 'anthropic/claude-fable-5' })JANUX_MODEL=provider/model- Provider key sniffing:
ANTHROPIC_API_KEY/OPENAI_API_KEY/GOOGLE_GENERATIVE_AI_API_KEY - Nothing set β the endpoint answers with a setup card; the app never crashes.
Performance
The documentation site is built with Janux (apps/docs) and scores 100 across the board β including Agentic Browsing, Lighthouse's check for whether an agent can actually read and operate the page. A CI job re-runs the audit on every pull request.
Packages
| Package | What |
|---|---|
janux |
Core: schema, signals, reactive state, component runtime, SSR islands, manifest, client resume + bridge, foreign interop, data cache, built-in client tools, glow, simulated agent cursor |
@janux/server |
api() RPC, file-system router (layouts, groups, matchers, middleware), HTTP handlers + uploads, HTML shell, /_janux/* endpoints incl. the hosted MCP + .md projections, llms.txt, Web Bot Auth |
@janux/agent |
Model resolution, providers, the tool loop with turn continuation, and the embedded harness: memory (in-memory/Postgres), durable workflows, guardrail processors, rate limiting (in-memory/Redis), attachments, outbound MCP client |
@janux/vite |
Vite plugin (SWC api stubs, SSR bridge, compile-time binding maps + opt-in per-intent code splitting) |
@janux/cli |
janux dev / build / start / verify / eval, plus the adapter API third-party deploy targets are written against |
@janux/node Β· @janux/vercel |
Deployment adapters: a self-contained build/ for any Node 24+ host, and a Build Output API directory for Vercel |
create-janux |
Scaffolder |
Documentation
janux.build β 114 pages, βK search, dark mode, and a copilot that answers from the docs themselves.
| Section | Start here |
|---|---|
| Getting started | What is Janux? Β· Quick start Β· The Agentic Web Β· Mental model |
| Guide | Components Β· Views and JSX Β· Intents and guards Β· Navigation Β· The agent and your copilot |
| Tutorial | A task board with two faces (3 parts) |
| Reference | one page per export: reactivity, client, data cache, agent harness, CLI |
| Recipes | Testing Β· Forms Β· Optimistic UI Β· Error handling Β· Custom server Β· Docker Β· Monorepo Β· Tailwind Β· Local model copilot |
| More | Examples Β· Comparison Β· Benchmarks Β· FAQ Β· Glossary |
Agents read the same docs at /llms.txt and any page as Markdown by appending .md.
Every example is verified. packages/docs-tests compiles every snippet, checks it imports only symbols the packages really export, runs the main example of a page and asserts what the prose claims. Three guards fail the build when an export has no reference page, when a page's executable claims aren't executed, or when any documented link stops resolving. Both backlogs are empty: every public export is documented, and every page that imports the framework has a test that runs it.
Benchmarks
19 multi-framework suites β client runtime, hydration, SSR, streaming and
shipped bytes β measuring Janux against react 19, preact, solid 2, svelte 5
and vue-vapor, with correctness gates before any number counts. The harness
is a port of octane's benchmarks (MIT,
Dominic Gannaway; js-framework fixtures derive from
krausest, Apache-2.0).
| Category | Where Janux stands |
|---|---|
| Resume vs hydration | 0.14Γ react β 0.39ms to make the news page interactive (react 2.86); 10.70ms vs 57.62 at 6Γ throttle |
| Shipped JS | 30.9KB gzip total vs react 62.1 (preact 10.0 Β· solid 14.1 Β· svelte 18.4 Β· vue-vapor 24.1); optional layers (glow, cursor, i18n, query cache) are imports that ship only when used; islands-free pages ship 0KB |
| Fine-grained updates | <For> + class={() => β¦}: swap 1.10ms vs react 3.98; reverse 1.95 vs 2.24; rotate 0.51 vs 1.51 |
| Mass DOM work | 10k rows: 68.94ms vs react 136.86; clear 38.40 vs 41.74; 512-field reset 14.74 vs 38.64; 512-field update pass 16.84 vs 45.58 |
| Whole-app suites | parity: lifecycle cycle 49.35ms vs 49.56, store integrations within Β±1.4Γ, suspense recovery within 1.14Γ |
| Building rows in bulk | behind: create-1000 6.56ms vs react 4.88 (solid 1.90) β a row carries an Owner, a signal and an effect |
| SSR throughput | behind: buffered 0.26ms vs react 0.07; streaming end-to-end at parity (50.86 vs 51.06) |
Across the 19 suites, 88 of 156 janux/react cells are ahead of react and 68 are
behind (2026-08-02 pass; bytes above are the 2026-08-06 measurement) β the full
signed table is in
benchmarks/BASELINE-2026-07.md.
Full tables, methodology and machine specs:
docs page Β· reproduce with
bun run bench from benchmarks/.
Templates
An example teaches a feature; a template starts a product. Each one is a complete app with its own README, a one-command deploy, and agent evals that prove its agent surface works β scaffold one and you have something to ship, not something to read.
bun create janux my-app --template dashboard
cd my-app && bun install && bun run dev
Run --template with no name and the gallery lists itself. Every template starts with no
API key: the copilot degrades to a setup card plus a no-model demo that drives the page
with real tool calls.
| Template | What you start with |
|---|---|
dashboard |
Incident triage whose copilot really operates the board β it acknowledges and resolves through the same tools the buttons call, and maintenance mode is confirm-guarded, so its call becomes a proposal a human approves. |
back-office |
A customers CRUD where who is asking changes what happens: routine edits execute, deleting parks in an approvals inbox, and one audit trail records the actor from the invocation origin. |
content-site |
Markdown with a typed frontmatter contract, served twice: pages for people, and llms.txt + per-page .md projections + a typed search tool for agents β the same code as the search box. |
Full gallery with screenshots: janux.build/docs/more/templates.
Examples
43 runnable apps, each a real Janux project β bun run --cwd examples/<name> dev.
Start here
| Example | What it shows |
|---|---|
shop |
The full picture: catalog source, debounced persist effect, confirm checkout with human approval, copilot included. |
hacker-news |
The canonical clone: streaming suspense front page, [page=integer] pagination, a server-rendered nested comment tree, useQuery refresh and hover prefetch. |
The agentic surface
| Example | What it shows |
|---|---|
with-web-agent |
The demo above: a console operated in natural language, createCopilot({ visualize }) for the chips/ring/veil, glowTarget for React Flow nodes that mount late, and a forbidden intent that forces the DOM fallback. |
human-in-the-loop |
Who invokes changes what happens: the same confirm intent executes on a human click but parks as a Proposal for an agent, with an approvals inbox and an origin-labeled audit trail. |
with-mcp-url |
The app as a bearer-protected MCP server by URL, with a committed tool contract (agent-contract.json) that turns CI red if the agent surface drifts. |
with-mcp-client |
The outbound direction: the app's agent connects to an external MCP server by URL, filters the remote tools and re-exposes them on its own surface. |
a2a-supplier |
The app as an agent for other agents: a derived /.well-known/agent-card.json, an A2A endpoint beside the MCP one, and a confirm guard that parks a remote agent's call for a human here. |
a2a-buyer |
The other side: discovers the supplier by its agent card and hires it over A2A, then follows the task while a human at the supplier decides. |
durable-agent |
The harness in production shape: Postgres conversation memory that survives restarts, Redis rate limiting, injection guardrails, a durable two-step workflow, and a schedule that triggers it and resumes the same run after the process is killed. |
with-subagents |
Agent composition: a front desk that delegates lookups to a budgeted research subagent (own prompt, intersected tools β never wider than the parent's) and hands money conversations off to a billing agent that answers from then on. |
with-local-llm |
The copilot's model runs in the browser over WebGPU (localLlm()), with supportsLocalLlm() detection, a serverLlm() fallback and a live localβcloud swap. |
agent-evals |
janux eval as a CI gate: scripted, model-free agent tasks replayed over the real webMCP surface, including a human approval step β plus a broken eval that proves the gate can fail. |
with-skills |
Skills: a multi-step returns procedure shipped as markdown the model loads on demand, projected to MCP β and janux verify failing on a skill that names a tool the app does not have. |
with-channels |
Channels: the same on-call agent answering in the browser and over an HTTP webhook β same confirm guard on both doors, and a browser-only intent the model is told it does not have. |
Janux MCP questions
How does Janux handle human-in-the-loop requirements?
Using the confirm guard, agent tool calls are paused as Proposals that require a human to approve or reject them via the actual UI.