> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# NSR MCP Server

> Use NSR as a verification oracle from any MCP host — the model proposes, NSR proves.

# NSR MCP Server

Exposes a **running** NSR API to any MCP host — Claude Code, Claude Desktop, the Agent SDK — as
agent-native tools and prompts.

## Why this exists

An LLM agent is a fallible neural reasoner. NSR turns a consequential call — *issue this refund,
grant this access, cancel this subscription* — from "trust the model" into **"the model proposes,
NSR proves."**

The intended pattern is NSR as a **verification oracle**: before acting, the agent routes the
decision through `nsr_decide` and proceeds only on an `approved` verdict backed by cited rules.

<Note>
  A `refused` verdict is the **correct, safe result** — not an error. The agent should ask for the
  missing facts or escalate, rather than guessing. The `verify_before_acting` prompt hands your
  host exactly this guardrail.
</Note>

## Configure

No npm dependencies. Node 18+ (for global `fetch`) and a hand-rolled JSON-RPC loop — nothing to
install.

| Variable         | Default                 | Meaning                                                         |
| ---------------- | ----------------------- | --------------------------------------------------------------- |
| `NSR_API_URL`    | `http://127.0.0.1:8080` | Base URL of the NSR server                                      |
| `NSR_API_KEY`    | —                       | Sent as `x-api-key` on every request. **Required**              |
| `NSR_ORG_ID`     | —                       | Optional `X-Org-ID` override                                    |
| `NSR_TIMEOUT_MS` | —                       | Per-request timeout, so an agent never hangs on a slow endpoint |

## Run

```bash theme={null}
# 1. A local NSR API
NSR_API_KEYS="mcp-demo-key" NSR_NEURAL_BACKEND=mock \
  ./target-local/release/nsr-server serve -p 8787

# 2. Point the MCP server at it
NSR_API_URL=http://127.0.0.1:8787 NSR_API_KEY=mcp-demo-key node nsr-mcp-server.mjs
```

<Warning>
  `NSR_NEURAL_BACKEND=mock` is **required offline**. The default backend calls an external
  embeddings API, so entity creation returns a 500 without it.
</Warning>

## Connect

```json theme={null}
{
  "mcpServers": {
    "nsr": {
      "command": "node",
      "args": ["/absolute/path/to/stateset-nsr/mcp/nsr-mcp-server.mjs"],
      "env": {
        "NSR_API_URL": "https://your-nsr-host",
        "NSR_API_KEY": "your-api-key"
      }
    }
  }
}
```

## Tools

**Decisions** — the flagship surface:

| Tool               | Purpose                                                                       |
| ------------------ | ----------------------------------------------------------------------------- |
| `nsr_decide`       | Verified decision: `approved` / `denied` / `refused` with a cited proof chain |
| `nsr_get_decision` | Retrieve a prior decision by id                                               |
| `nsr_verify_plan`  | Check a multi-step plan before executing it                                   |

**Teaching it rules and facts:**

| Tool                 | Purpose                              |
| -------------------- | ------------------------------------ |
| `nsr_add_rule`       | Add a rule to the org knowledge base |
| `nsr_add_fact`       | Assert a fact                        |
| `nsr_add_entity`     | Create an entity                     |
| `nsr_apply_template` | Apply a policy template              |
| `nsr_list_templates` | List available templates             |

**Reasoning and inspection:**

| Tool                 | Purpose                           |
| -------------------- | --------------------------------- |
| `nsr_chat`           | Run the chat pipeline             |
| `nsr_forward_chain`  | Forward-chain inference           |
| `nsr_backward_chain` | Backward-chain a goal             |
| `nsr_query_kb`       | Query the knowledge base          |
| `nsr_gss_seed_info`  | Grounded Symbol System seed state |
| `nsr_flywheel_curve` | Read the learning curve           |

## Which NSR MCP server?

<Warning>
  There are two, and they are not equivalent. The in-process Rust binary (`nsr_mcp`) embeds an
  engine and **stubs** the reasoning tools. Use the Node server documented here for the full, live
  reasoning surface.
</Warning>

## Client-side validation

The server validates input before calling the API and names the exact malformed rule or field,
rather than surfacing a cryptic 422 deserialize error — worth knowing when an agent is authoring
rules and getting them wrong.

## Related

* [Verified Decisions API](/stateset-nsr-decisions) — the `/v1/decisions` contract these tools wrap
* [Neuro-Symbolic Architecture](/stateset-nsr)
* [All MCP servers](/mcp-servers)