Start the Celorga MCP server

Install the npm package, then start the local stdio server with an absolute corpus path:

npm install --global celorga
celorga mcp serve --dir /absolute/path/to/notes

The process speaks MCP over standard input and output. Normally an MCP client starts and supervises it; you do not keep a separate network service running.

codex mcp add org2 -- celorga mcp serve --dir /absolute/path/to/notes
codex mcp list

claude mcp add --transport stdio --scope user org2 -- \
  celorga mcp serve --dir /absolute/path/to/notes
claude mcp get org2

{
  "mcpServers": {
    "org2": {
      "type": "stdio",
      "command": "celorga",
      "args": ["mcp", "serve", "--dir", "/absolute/path/to/notes"]
    }
  }
}

Connect to a headless Celorga server

The headless server can expose the selected corpus through a separate read-only Streamable HTTP MCP listener on its Tailscale address. Initialize and build the server as described in Headless Celorga server, then preview and create a client credential:

celorga server token create --name chatgpt
celorga server token create --name chatgpt --apply
celorga server start

Creating the first token enables the endpoint. The applied command prints the token exactly once; Celorga stores only its SHA-256 hash in the private machine-local server configuration. Restart an already running server after token, port, origin, or MCP state changes. server status reports the endpoint and non-secret token metadata.

Codex CLI and the ChatGPT desktop app can use the URL and a token stored in an environment variable:

[mcp_servers.openorg]
url = "http://100.64.0.1:48923/mcp"
bearer_token_env_var = "OPENORG_MCP_TOKEN"

The listener binds only to the configured Tailscale IPv4 address. Tailscale encrypts that private-network hop, but the URL itself is HTTP. The server does not terminate public TLS or publish itself to the internet. A hosted system such as ChatGPT web needs an HTTPS endpoint it can reach and, for ChatGPT, a plugin containing the remote MCP server. Put an authenticated TLS reverse proxy or tunnel in front only after reviewing its disclosure boundary. See the official OpenAI MCP setup guide for the current distinction between local clients and hosted ChatGPT tools.

The HTTP endpoint accepts POST /mcp with Authorization: Bearer TOKEN. It is stateless, negotiates the MCP 2025-03-26 protocol profile, returns JSON responses, accepts individual messages or batches of at most 100 messages, and returns 405 for the optional GET event stream. It rejects unknown browser origins unless they were explicitly allowlisted with server mcp enable --allow-origin ORIGIN --apply and caps request bodies at 2 MB. These transport choices follow the official MCP Streamable HTTP contract. It does not expose the three write tools available through trusted stdio. Create a separate token per client so access can be revoked independently:

celorga server token list
celorga server token revoke --id TOKEN_ID
celorga server token revoke --id TOKEN_ID --apply

What the server exposes

The current tools are:

• org2_search: rank bounded matches and return canonical file, source-range, and citation metadata.

• org2_fetch: retrieve one note or heading by stable ID with bounded source and optional backlinks or neighbors.

• org2_context: assemble bounded, cited context for a question without calling a model.

• org2_agent_profile_resolve: resolve a runtime identity to a portable agent profile and primary goal.

• org2_run_create: instantiate a reusable workflow as a durable run.

• org2_run_transition: move a run through its lifecycle; completion requires a reviewer-facing summary.

• org2_run_list: inspect durable runs and review state.

• org2_thread_post: post an attributed, idempotent background update to an existing AI chat without starting a model turn.

The read-only retrieval tools share the same incremental compiler and cited context substrate as celorga agent search|fetch|context. Result counts and context characters are capped by their schemas. Resource listing is paginated in stable lexical order, and resource reads include a SHA-256 revision plus line count. The server is still not a complete mirror of the CLI: Agenda, TODO mutation, publishing, lint, graph checks, and other specialized commands remain CLI operations. Use the general skill below so an agent knows when to leave MCP and call CLI JSON.

Corpus and safety boundaries

• --dir selects the only corpus exposed by that server process.

• Resource reads stay beneath the canonical corpus root, reject symlinked files, hidden runtime state, archives, and ignored sync artifacts, and expose only canonical .org source.

• Workflow prompts and resource listing are read-only.

• The headless HTTP endpoint exposes only org2_search, org2_fetch, org2_context, org2_agent_profile_resolve, and org2_run_list. Every HTTP token currently has only the corpus:read scope.

• Trusted stdio additionally exposes run creation, run transition, and thread posting. Those are writes. They use the same guarded Celorga records and lifecycle rules as the CLI, but the MCP call itself is the requested action; there is no second --apply preview inside those tools.

• Credentials are not read from corpus files or returned as MCP resources. Keep client secrets in the client environment or its credential store.

Only enable stdio write tools for agents you trust to act within that corpus. If a client supports per-tool approval, require confirmation for the three mutating tools. Retrieval and coordination tools carry MCP readOnlyHint annotations so compatible clients can apply an appropriate approval policy.

Quick protocol check

This low-level smoke test initializes the server and lists resources without making changes:

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized","params":{}}' \
  '{"jsonrpc":"2.0","id":2,"method":"resources/list","params":{}}' \
  | celorga mcp serve --dir /absolute/path/to/notes

You should receive an initialize result and the first sorted resources page. A trusted stdio client connection test should additionally show eight tools and the corpus's workflow prompts; the read-only HTTP endpoint shows five tools.

Install the general Celorga skill

The npm package includes the canonical portable skill at skills/org2/SKILL.md. Install a corpus-owned copy with a preview first:

celorga skill install --dir /absolute/path/to/notes
celorga skill install --dir /absolute/path/to/notes --apply

The destination is .agents/skills/org2/SKILL.md. The installer creates only a missing file. If that path already contains a user-managed copy, it reports a conflict and never overwrites it. Use --format json for automation.

Codex discovers repository skills from .agents/skills; other skill-aware runtimes can point at or copy the same standards-shaped directory. Celorga includes the general skill in every newly created starter workspace so those external agents can discover it. Inside Celorga, the equivalent core guidance is part of every AI chat's ambient operating context instead of a separate /org2 command. See the official Codex skill guide for Codex discovery and invocation.

Celorga as an MCP client

Do not confuse the inbound server above with Celorga's outbound MCP snapshot commands:

celorga mcp client-add crm --command crm-mcp --arg=--stdio \
  --capability accounts --env CRM_TOKEN --dir /absolute/path/to/notes
celorga mcp discover crm --snapshot crm-capabilities \
  --dir /absolute/path/to/notes --json

mcp client-add records an external server declaration in .org2/mcp-clients.json. mcp discover inspects that external server, and mcp snapshot can preserve an external result under raw/connectors/mcp/ with provenance. Environment-variable names may be recorded; their secret values remain machine-local.

For every CLI family and flag, continue to Tooling reference. For the general agent operating contract, see Agent quickstart.