Claude Code and Codex Setup

This is the canonical setup guide for using GridWonk tools from Claude Code or OpenAI Codex. It supports two access lanes:

Plugin 0.2.6 displays as GridWonk Internal and retains the gridwonk package identity, both existing servers, and the bundled docs, tasks, and admin workflow skills. Update an installed plugin and start a new session to load those bundled instructions.

MCP means Model Context Protocol: a standard way for an AI tool to discover and call another application's tools. Both Claude Code and Codex support MCP.

Choose one lane. External users do not need the private GridWonk repository and must not be given internal admin credentials.

Before You StartCopy Anchor Link

You need:

• Claude Code or Codex installed and signed in.
• A current Node.js release only for the internal repository plugin. The GridWonk repository uses Node.js 24.
• Your own GridWonk credential, issued for the organization and environment you are authorized to use.

Keep credentials in environment variables or an approved secret manager. Never commit them, paste them into an AI chat, or copy another person's credential.

The current production URL is:

https://gridwonk.com

External SetupCopy Anchor Link

External users connect to the hosted runtime endpoint:

https://gridwonk.com/api/v1/mcp

The hosted endpoint supports stateful Streamable HTTP sessions. OAuth clients should request resource=https://gridwonk.com/api/v1/mcp; the session is then pinned to that token audience and partner scope set, when present. The local stdio package bridges to the same Streamable HTTP endpoint.

Use an organization-scoped GridWonk runtime API key for the broad tool catalog. Use a short-lived OAuth token carrying partner.read, partner.write, or both when the client needs packet tools; a raw key never discovers packet tools, and a scoped token never discovers broad tools. The examples use the canonical GRIDWONK_API_KEY environment variable. Pre-rebrand GRIDBOOST_* names remain accepted temporarily for existing hosts, but new configuration should use GRIDWONK_*.

The local connector applies that same split. Hosted MCP also exposes assist through the shared server runtime; an existing local release may retain its REST helper. Assistant execution remains deployment-gated and subject to organization admission. Partner, mixed, empty or unknown-only catalogs never gain broad assistant authority. Broad customer credentials can also discover project list, get, create, and update tools. Those tools are developer-organization scoped and intentionally omit submit, resubmit, and synthetic-demo creation.

Eligible utility callers use the existing start_packet_review tool with partner.write; the server selects utility authority and checks the utility lane and current write membership. Four Salesforce-specific tools are implemented but disabled by default and exposed only to authorized connector callers after approved enablement. See the Salesforce integration status before planning Agentforce or Salesforce-hosted MCP connections; neither direction is activated by connecting this client.

The connector identifies each running process with one anonymous instance ID and a versioned user agent. Closing Claude Code, Codex, or the parent stdio connection closes the hosted MCP session too; cleanup has a bounded timeout so a stalled remote connection cannot keep the local process alive. The package manifest, modern and fallback handshakes, and that user agent share one release version. After upgrading the connector package, fully restart the client so this lifecycle behavior and the current hosted catalog are both loaded. Use package 0.3.2 or later (0.4.0 is current). A 401 or 403 stops after the modern request instead of retrying the same credential through the legacy proxy. If logs show many rejected requests with different instance IDs, correct the credential, remove duplicate gridwonk/gridwonk-admin registrations, and restart the MCP host; that pattern is repeated process startup, not one healthy session polling.

Authorized internal Codex sessions may use the separate gridwonk-admin catalog to inspect organizations, members, grants, explicitly scoped agent sessions, and the model catalog. Organization responses omit payment identifiers and private settings, and session responses omit free-form metadata. Impersonation, billing overrides, and model-catalog writes are not delegated to Codex.

The protected organizations.activity.list tool also provides bounded organization-owned packet activity, upload-attempt states and linked automatic outcomes. Use its actor/date/category filters and pagination, and retain its coverage warnings: missing events are not proof of feature non-use. It is read-only, contains no provider errors or raw metadata, and does not expose personal user analytics or repair actions. External customer credentials cannot use this Admin tool.

Make the variable available to the process that starts Claude Code or Codex:

export GRIDWONK_API_KEY='gw_live_...'

Use your secret manager's shell-injection feature when available so the value is not stored in shell history.

Claude Code — ExternalCopy Anchor Link

Create or update .mcp.json in the external user's project. The file may be committed because it references the environment variable without containing its value:

{
  "mcpServers": {
    "gridwonk": {
      "type": "http",
      "url": "https://gridwonk.com/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${GRIDWONK_API_KEY}"
      }
    }
  }
}

Start Claude Code from that project, accept the MCP trust prompt, and run:

/mcp

The gridwonk server should be connected and should list organization-scoped runtime tools.

Codex — ExternalCopy Anchor Link

Add the hosted server without writing the credential into Codex configuration:

codex mcp add gridwonk \
  --url https://gridwonk.com/api/v1/mcp \
  --bearer-token-env-var GRIDWONK_API_KEY

Verify the saved connection:

codex mcp list --json
codex mcp get gridwonk --json

Restart Codex if it was already open when the server was added.

External Smoke TestCopy Anchor Link

Use a read-only prompt first:

Use the GridWonk MCP server to search public documentation for "MCP setup".
Do not create, update, cancel, approve, or delete anything.
Report the server and tool name you used.

The call should use the gridwonk server and search_docs tool. Results remain scoped to the API key's organization.

For a packet-tool smoke, create a separate connection whose Bearer environment variable contains a partner-scoped OAuth token. partner.read should list only the currently registered read tools; partner.write should list only the registered mutation tools. Do not expect search_docs, resources, or prompts on that scoped connection.

Use The Connected RuntimeCopy Anchor Link

After the read-only setup checks, use tools/list to discover the tools available to the current credential and protocol revision. The MCP API reference maintains the full catalog and scope rules. The docs-host /.well-known/mcp.json requires a docs session; API-key and OAuth clients can use authenticated GET /api/v1/mcp for runtime metadata.

Continue A Work ItemCopy Anchor Link

These tools require a broad credential and a modern stateful MCP session. The local connector maintains that session; direct HTTP clients must follow the session lifecycle.

1. Call get_active_work_item with {} to inspect the context already bound to this session.
2. To resume another item, call list_recent_work_items with {"limit": 5} and select the intended result. Pass its actual work-context ID to set_active_work_item as workContextId.
3. Call get_active_work_item again to verify the binding before asking chat a follow-up through its message argument. Requirement and application queries can inherit this context.
4. Before starting unrelated work, call clear_active_work_item with {} to clear inherited context, then bind the intended new work item explicitly.

Keep the same MCP session for follow-ups. If access changes or the session expires, initialize a new session and inspect its context before continuing. A work-context ID does not grant access to another organization or another person's private documents. When reporting a chat result, retain its citations and disclose a partial answer or error; see the chat result contract.

Create And Inspect A Supported JobCopy Anchor Link

Job tools belong to the broad credential catalog. First use list_jobs and get_job_status to inspect existing work. Once the user has authorized the exact new work and you have established the target organization, utility, and state, a discovery call can use these tool arguments:

{
  "name": "run_job",
  "arguments": {
    "jobType": "discovery",
    "utilityName": "duke-energy",
    "state": "NC"
  }
}

Replace the example utility and state with the authorized target. Save the returned jobId and call get_job_status with {"jobId": "<returned-job-id>"}. Follow the returned polling instructions; per-user OAuth callers use the MCP polling tool rather than API-key-only REST URLs. Creation means the job was accepted, not completed. If the start response is lost or ambiguous, inspect existing jobs before creating another.

The other supported new job type is document-digitization, which requires an authorized metadata.documentId and metadata.tableName: "ix_procedure_documents" for procedure documents. See the Jobs API for metadata and access rules. Historical site-control, deficiency, and report-generation jobs remain readable but cannot be created again, including through admin tasks.run. Current packet validation uses Packet intake Review.

There is no standalone job-retry MCP tool. A separately authorized replacement of a supported job creates a new job ID. To cancel authorized active work, call cancel_job with its exact jobId and read the returned cancelled, runtime, and warning fields; an in-flight provider call may still finish after cancellation.

Internal SetupCopy Anchor Link

This lane requires access to the private GridWonk/gridwonk GitHub repository. The shared plugin runs the repository's local connector, so start Claude Code or Codex from the repository checkout.

Prepare The RepositoryCopy Anchor Link

git clone git@github.com:GridWonk/gridwonk.git
cd gridwonk
git pull --ff-only origin main
npm ci

Supply only the credentials needed for your role to the process that starts Claude Code or Codex:

export GRIDWONK_BASE_URL=https://gridwonk.com
export GRIDWONK_API_KEY='gw_live_...'
# Authorized internal operators only:
export GRIDWONK_ADMIN_API_KEY='gw_live_...'

• GRIDWONK_API_KEY is an organization-scoped runtime key.
• GRIDWONK_ADMIN_API_KEY is optional and is restricted to approved GridWonk internal management keys.
• GRIDWONK_CLIENT_USER_ID and GRIDWONK_DELEGATION_TOKEN are optional and may be used only for an approved delegated-user workflow.

Do not provide an admin key to an external user. A customer runtime or customer management key cannot call the protected GridWonk admin endpoint.

Plugin 0.2.3 and later do not read .env.local, .env, or any other repository environment file. Use an approved secret manager to inject the variables when possible. If the credential required by a configured connection is absent, the launcher exits before making a network request. The underlying server's explicit --api-key option remains supported for MCP hosts that already use it, although the repository plugin manifest uses process environment injection. The skills and both MCP servers ship as one plugin, so disabling it removes the skills too. To run the skills without a given MCP connection, simply leave that connection's credential unset: the skills keep working and only that launcher exits.

Claude Code — InternalCopy Anchor Link

The repository declares gridwonk@gridwonk-private in .claude/settings.json. After the repository is trusted, accept Claude Code's prompts to add the private marketplace and install the plugin.

If the prompts were previously skipped, run:

claude plugin marketplace add GridWonk/gridwonk --scope local
claude plugin install gridwonk@gridwonk-private --scope local

Then start a new session or run:

/reload-plugins

Verify the installation:

claude plugin validate .
claude plugin validate ./plugins/gridwonk
claude plugin marketplace list --json
claude plugin list --json

The plugin ID must be gridwonk@gridwonk-private and enabled. In Claude Code, the following skills should be available:

/gridwonk:gridwonk-docs
/gridwonk:gridwonk-tasks
/gridwonk:gridwonk-admin

Codex — InternalCopy Anchor Link

For local development worktrees, select the checked-in gridwonk-core environment in .codex/environments/gridwonk-core.toml. Automatic setup links configuration only. Use its explicit Install dependencies action when execution is needed; that action selects the pinned Node.js and npm versions, checks free space, and runs the guarded install without browser downloads. The runner also provides check, unit-test, type-check, lint, dev-server, local-build, and Chromium-install actions. See .codex/environments/SETUP.md for details.

Setup links optional local configuration from the main checkout when available, preserves real worktree files, and skips missing sources. It does not link _memory/. The check action reports whether .env.local exists without reading its values; plugin credentials and backend access still need the separate checks below.

Add the repository-backed marketplace and install the same plugin:

codex plugin marketplace add GridWonk/gridwonk --ref main
codex plugin add gridwonk@gridwonk-private

Verify it:

codex plugin marketplace list
codex plugin list

Fully quit and reopen Codex after the first installation. Search the plugin picker for GridWonk; the plugin ID is gridwonk@gridwonk-private.

Internal Smoke TestsCopy Anchor Link

Run read-only checks before allowing a tool to mutate platform data:

Use the GridWonk docs skill to search public documentation for "MCP setup".
Use the GridWonk tasks skill to list recent jobs without starting or cancelling anything.
If I am an authorized internal operator, use the GridWonk admin skill to list pending users without changing them.
Report the server and tool name used for each check.

The only MCP server names installed by plugin 0.2.3 and later are gridwonk and gridwonk-admin. The older gridboost and gridboost-admin aliases were removed because the duplicate registrations made every session spawn four processes for two servers and show each tool twice.

Authorization RulesCopy Anchor Link

Protected document recovery is a human-operator exception, not a setup smoke test. The Admin implementation declares documents.recovery.preview, .apply, and .get; management API keys cannot use them. A session or separately enabled administrator OAuth lane must retain current platform authority. Apply additionally binds the preview token, exact targets, numeric spending ceiling and absolute deadline. Missing qualified pricing refuses provider calls. Migration, release and each paid recovery require their own approval; a connected plugin does not authorize execution. These tools are absent from public MCP, customer SDK/CLI and chatbot mutation surfaces.

The Admin plugin also exposes confirmed user, invitation, team access, ownership, branding, organization-feature and model-assignment actions. Use the matching preview/apply pair with one UUID idempotencyKey and the unchanged payload; apply additionally requires the opaque confirmationToken from preview. Approval lasts ten minutes and binds the actor, credential, lane, tool, organization and state. An exact successful retry returns the stored safe receipt with replayed: true for 24 hours. Changed reuse is refused; executing, ambiguous or failed results require inspection and a new preview. A connection or preview alone does not authorize a live change.

Organization features use organizations.features.get, followed by organizations.features.preview_update / organizations.features.apply_update. Resolve an explicit organization and choose one catalog feature and action: "enable", "disable" or "reset", with a written reason. Reset clears the override. Inspect the preview's effective availability before applying: environment overrides or dependencies may prevent the saved choice from taking effect. These tools require current platform-admin authority and cannot change global defaults, customer self-service policy or release controls requiring a deployment. Reread with get after apply.

These mutations require a browser admin session, or an internal management key or administrator OAuth connection after the separately authorized ADMIN_MCP_REMOTE_MUTATIONS_ENABLED=true rollout. The flag defaults off, depends on the reviewed organization administration merge and four verified database guards. Administrator OAuth also requires its independently enabled lane, approved client and current role/membership. The legacy agent_model_configs.update stays session-only and deprecated. Invitation acceptance and legal consent remain invitee-only. Team owner/admin and last-owner checks, sign-in-domain isolation and model-catalog validation remain enforced by the shared services. See MCP Servers — Admin Tools.

• Default to read-only calls during setup and testing.
• Keep every runtime request organization-scoped.
• External users use only the hosted gridwonk runtime connection.
• Only approved GridWonk internal operators may use gridwonk-admin.
• Preview a supported admin change before applying it.
• Treat the synthetic-project cleanup tools as a narrow exception, not general deletion: use only exact empty Seven States synthetic-loop draft IDs and carry the preview token and unchanged inventory digest into apply.
• Never run, cancel, approve, update, or delete production data unless the user has explicitly authorized that exact action.
• A successful connection does not grant permission for a mutation.
• For Salesforce-owned copies, ordinary packet reads still require the effective human viewer's current Salesforce record and field permissions. A shared service credential is not a substitute for that person's access, including for historical reports.

TroubleshootingCopy Anchor Link

The server or plugin is missingCopy Anchor Link

1. Confirm Claude Code or Codex is current.
2. Confirm the setup command was run from the intended project or repository.
3. Confirm the marketplace and plugin ID are exactly gridwonk@gridwonk-private for the internal lane.
4. Reload Claude plugins or fully restart Codex.

Authentication failsCopy Anchor Link

1. Confirm GRIDWONK_BASE_URL is https://gridwonk.com.
2. Confirm the required environment variable is present without printing its value.
3. Confirm the credential belongs to the intended organization and environment.
4. Confirm an internal management key, not a customer key, is being used for the protected admin lane.
5. Ask a GridWonk administrator to issue or rotate your own credential; do not borrow another user's key.

Internal skills load but MCP calls failCopy Anchor Link

1. Run npm ci in the repository root.
2. Confirm the required credential is explicitly present in the parent process environment without printing its value. Repository environment files are intentionally ignored by the launcher.
3. Confirm the installed plugin is version 0.2.4 or later: claude plugin list --json reports the version and the MCP servers it registers; codex plugin list reports only the version, so use codex mcp list to confirm just the gridwonk and gridwonk-admin connections are present.
4. If the installed version is older, fetch the update first (claude plugin update gridwonk@gridwonk-private; for Codex, upgrade the marketplace and reinstall) — restarting applies an already-fetched update, it does not fetch one. Then fully restart the task or application so it loads the installed plugin version and the repaired process environment. Reconnecting an existing connection does not update plugin code. The installed plugin supplies the launcher, so an older copy of the launcher in the task's worktree cannot bypass the fix.

Reusable Setup PromptCopy Anchor Link

Copy this prompt into either Claude Code or Codex:

Set up this machine to use GridWonk safely.

First, read the canonical guide in the GridWonk repository at:
content/docs/integrations/agent-tools.mdx

If that repository file is unavailable, use the published copy at:
https://docs.gridwonk.com/integrations/agent-tools

Determine whether I am:
1. an external GridWonk customer or partner, or
2. an authorized internal GridWonk developer/operator.

Also detect whether this tool is Claude Code or OpenAI Codex, then follow only
the matching access lane and tool instructions from the guide.

Rules:
- Never print, echo, commit, or paste an API key into chat.
- Never give an external user the internal plugin or admin MCP connection.
- Use a least-privilege organization runtime key for external setup.
- Use the internal admin lane only when the user is an authorized GridWonk
  operator and already has their own approved management credential.
- Do not create, update, cancel, approve, or delete anything during setup.
- Run the guide's read-only verification and smoke tests when setup is complete.
- Report the installed plugin or MCP server names, the tests that passed, and
  any missing credential or access requirement without exposing secret values.

This page is the source of truth. Tool-specific compatibility pointers elsewhere in the repository should link here instead of copying these instructions.

One behavior note for requirement queries made through these tools: published requirement rows carry a per-row reviewStatus of approved or pending (utility-rejected rows never appear). External tools use query_published_requirements; the retired public query_requirements tool is no longer advertised or callable. See Requirements API for the contract.