MCP Framework

Nella’s MCP package ships two concrete runtimes rather than a generic “tool framework” abstraction: a local stdio server for coding agents and a hosted HTTP server for shared deployments.

Runtime Modes

Local Stdio MCP

Use the local server when the agent is working directly against one repository:

nella mcp --workspace /path/to/project

# direct package entrypoint
npx -y @getnella/mcp --workspace /path/to/project

The stdio server:

• requires an explicit --workspace
• initializes session context under .nella/
• exposes the current 7-tool local surface
• issues trust-chain metadata through nella_get_context

Hosted HTTP MCP

Use the hosted server when you need API keys, rate limits, shared deployment, or a network-accessible MCP endpoint:

nella serve --port 3001

The hosted server:

• serves MCP over POST /mcp
• exposes GET /health
• opens /ws for the hosted WebSocket bridge
• validates API keys through Supabase
• uses Redis when REDIS_URL is available, with in-memory fallback otherwise

Current Tool Surface

Nella currently exposes 7 MCP tools across 3 categories:

Category	Tools	Count
Search	nella_index, nella_search	2
Context	nella_get_context, nella_add_assumption, nella_check_assumptions, nella_check_dependencies	4
Trust chain	nella_heartbeat	1

See the MCP Tools Overview for the tool-by-tool reference.

Execution Model

Each request follows a straightforward runtime path:

Request → Tool lookup → Handler execution → MCP response

What changes by mode:

• local stdio adds workspace-bound session state and trust-chain setup
• hosted HTTP adds authentication, rate limiting, and usage logging
• both runtimes return tool errors as MCP error responses when execution fails

Trust Chain

Nella uses nella_get_context and nella_heartbeat to help clients verify session continuity.

nella_get_context returns:

• the current session overview
• trust-token guidance
• HMAC integrity guidance
• the current heartbeat challenge

nella_heartbeat accepts that challenge and returns the next one, allowing the client to continue the chain across tool calls.

Schemas and Client UX

Each tool definition includes a JSON Schema inputSchema. MCP clients use that metadata to:

• render tool forms
• validate arguments before sending calls
• describe parameters in their tool picker UI

Runtime handlers still enforce operational preconditions such as:

• --workspace being present for local MCP
• the search index existing before nella_search
• hosted environment variables being configured for nella serve

Hosted Requirements

The current hosted implementation requires:

Variable	Purpose
SUPABASE_URL	Hosted auth and data access
SUPABASE_SERVICE_ROLE_KEY	Server-side Supabase access
REDIS_URL	Optional shared rate limiting
PORT	Optional HTTP port override

What This Page Does Not Claim

The current public @getnella/mcp package does not document a package-level surface for:

• tool version negotiation
• package-level nella_set_context
• response caching across tool calls
• a public nella playground CLI command

Those concepts still exist in parts of the broader codebase, but they are not the shipped MCP surface documented on this site today.