cmd mcp

nself mcp

Start the nSelf MCP server: a tool for every exposed command, plus resources and prompts, for Claude Code and other MCP clients.

Synopsis

nself mcp <subcommand> [flags]

Description

nself mcp starts a Model Context Protocol server that exposes nSelf as tools, resources, and prompts. MCP clients (including Claude Code) can then call those directly, without leaving their coding environment.

By default the server runs over stdio, which is the correct mode for Claude Code's mcpServers configuration. Use --transport sse or --transport http (streamable HTTP) to expose the server over a local port instead — set NSELF_MCP_TOKEN to require a bearer token on those two transports (stdio has no network exposure, so it never needs one).

nself mcp must be run from inside a directory that contains an nSelf project (i.e. one initialised by nself init). The server exits immediately if no project is found.

Tools

The tool list is generated, not hand-written: one tool per exposed command of the command registry, with its summary, side effect, whether it asks for confirmation, and a link to its input schema. See MCP-Tools for the current list. The 26 tools earlier releases registered by hand keep working under their old names; each is either the generated tool of the same name or a deprecated alias of one (see MCP-Server).

Every tool call runs the command as a child of the nself binary itself (resolved via os.Executable(), never a bare "nself" on PATH) with --json, so the result is the command's own v1 envelope. A tool that changes state outside the project returns confirmation_required first; repeat the identical call with the confirm value to run it.

Resources (4)

Name	Description
nself://config	Project config snapshot
nself://env	Effective env cascade inputs
nself://services	Service inventory
nself://urls	Service URLs

nself://env lists every env file present in the project (secrets redacted) but deliberately does not compute which file wins for a given key — that precedence is being revised (see nself env explain on the roadmap); ask the CLI, not this resource, for the authoritative answer.

Prompts (3)

Name	Description
add-service	Enable an optional service (or install a plugin) and bring it up safely
diagnose-failure	Investigate why an nSelf service is unhealthy or a project won't start
prepare-deploy	Run the pre-deploy checklist before promoting a project to staging or prod

ɳSentry Tools: AI Agents Operate Monitoring

The five sentry_* tools wrap the same typed client the cmd-sentry command group uses, so any MCP-capable AI agent can operate monitoring end to end. No dashboard visit needed.

Authentication resolves in this order: NSELF_SENTRY_API_KEY environment variable, then ~/.nself/sentry.json (written by nself sentry login). Set NSELF_SENTRY_API_URL to target a self-hosted or local sentry bundle instead of the hosted SaaS.

Example prompts an agent can now handle:

Add an uptime monitor for https://api.example.com checked every minute.

Any open incidents right now? Acknowledge the critical one and summarize it.

Is our status page fully operational? If a component is degraded, list it.

List every monitor slower than a 60s interval and tell me which ones to tighten.

Write tools respect tier quotas server-side (free: 10 monitors at 5-minute intervals). The API returns a quota error with an upgrade hint when a limit is reached. Monitor deletion is deliberately not exposed over MCP; use nself sentry monitors rm from the CLI.

nself_run_migration DDL Allowlist

The nself_run_migration tool enforces a DDL allowlist before executing any SQL. This prevents AI Studio sessions or automated agents from running destructive statements via confirm: true set programmatically.

Permitted statement types:

• CREATE TABLE IF NOT EXISTS
• ALTER TABLE ADD COLUMN
• CREATE INDEX
• CREATE EXTENSION
• CREATE POLICY
• INSERT with an explicit column list
• UPDATE with a WHERE clause
• DROP POLICY

Blocked statement types (return an error without executing):

Blocked prefix	Why
DROP TABLE	Irreversible data loss
DROP DATABASE	Irreversible data loss
DROP SCHEMA	Irreversible data loss
TRUNCATE	Irreversible data removal
DELETE FROM	Unbounded data removal
ALTER ROLE	Privilege escalation
GRANT	Privilege escalation
REVOKE	Privilege removal
\copy	psql meta-command, data exfil risk
\connect	psql meta-command, connection switching

The check is case-insensitive and strips leading SQL comments (-- ...) so that comment-prefix bypasses are also blocked.

For blocked statement types, run nself db migrate directly from the CLI.

Flags

Name	Shorthand	Type	Default	Env	Escalates to	JSON override	Description
--allowed-host		stringSlice	[]				Host name this server is reachable under; required (repeatable) for a non-loopback --host
--host		string	127.0.0.1				Bind address for the sse/http transports
--port	-p	int	3825				Port for the sse/http transports
--transport	-t	string	stdio				Transport: stdio, sse, or http
--help	-h	bool	false				Show help

Subcommands

Name	Description
setup	Print or write the MCP client config and AGENTS.md for this project

Contract

• Side effect: read
• Output: stream
• JSON: none
• Exit codes: none declared

Examples

# Run as a Claude Code MCP server using stdio (recommended)
nself mcp

# Run as an SSE server for browser-based clients
nself mcp --transport sse

# Run SSE on a custom port
nself mcp --transport sse --port 4000

# Run the streamable-HTTP transport
nself mcp --transport http --port 4000

# Require a bearer token on the sse/http transports (stdio never needs one)
NSELF_MCP_TOKEN=$(openssl rand -hex 32) nself mcp --transport http

Claude Code configuration

Add the following to your project's .claude/settings.json:

{
  "mcpServers": {
    "nself": {
      "command": "nself",
      "args": ["mcp"]
    }
  }
}

Claude Code will start nself mcp automatically and connect over stdio.

See Also

• cmd-doctor — run the nSelf diagnostics suite
• cmd-plugin — manage the plugin catalog
• cmd-start — start the nSelf stack

← Commands | Home →