A short operating guide for connecting a coding assistant to Nykst: what the token can read, what every tool is allowed to do, and how to revoke access.

A token is a read key, not a deploy key

The MCP endpoint accepts a bearer token created on the MCP page. The raw token is returned once at creation. The server stores a SHA-256 hash and a short prefix, not the token itself. The hashing function is at src/lib/mcp.server.ts:20, token creation starts at line 24, and the record stores only token_hash and token_prefix at lines 33 and 34.

Each request resolves the token by hash and rejects it when it is missing or revoked. The lookup is at src/lib/mcp.server.ts:63 and filters on revoked_at at line 71. There is no fixed expiry column in this tree. Treat a token as valid until you revoke it, and revoke it when the assistant no longer needs access. The revoke function is at line 54 and only matches a token owned by the signed-in user.

Every tool is marked read-only

The tool layer is documented as read-only at src/lib/analysis/tools.ts:7. The test at tests/analysis-tools.test.ts:90 walks the full published tool list and asserts readOnlyHint: true for every tool on line 98. That test covers all 11 tools, including the three that produce a simulated result: simulate_change, generate_fix_patch and run_safe_code_loop. None of them writes to your repository. They return a patch or a simulated graph for you to inspect.

Read-only does not mean risk-free. A read tool can still expose source paths, file names and code windows to the assistant you connected. Only connect repositories you are willing to show that assistant, and read the tool output before you paste it into another service.

Start with three tools

The full profile contains 11 tools. For a first session, three are enough to answer the question most changes start with:

get_impact returns the files, importers, runtime dependents and entrypoints for one path or symbol.
find_usages finds a named symbol, table, endpoint or environment variable across the analyzed repository.
search_files finds a path or text window when you need to locate the file before you know its name.

Add simulate_change only when you have a concrete diff to test. It returns a simulated impact result; it does not apply the diff. Add the patch tools only after you have a reviewed target file and are prepared to read the returned diff. A complete list is published at /mcp.

A request you can inspect

The endpoint speaks MCP over HTTP. The token belongs in the Authorization header, never in a URL, a screenshot or a chat message. This is the shape of a tools call, with the value replaced by an environment variable:

curl -s https://nykst.unifies.codes/api/mcp \
  -H "Authorization: Bearer $NYKST_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Run tools/list first and compare the names and annotations with the test above. If a tool is missing, or a tool reports a write capability, stop and report it rather than guessing.

What access is scoped to

A token is tied to the GitHub account that created it. Snapshot loading filters on the provider user id at src/lib/mcp.server.ts:82 and later, so one token cannot read another account's connected repositories by naming them. The token summary shows a prefix and a label, not the secret. Revoking it sets revoked_at; the next request fails authentication.

What this does not cover

This guide does not claim that the MCP endpoint is a sandbox for untrusted code. It reads an analysis snapshot produced by the ingestion pipeline. Connect only repositories you control, and treat the assistant's output as a suggestion that still needs a human review. The three-tool starting set above is a recommendation, not a server-enforced default in this tree. The full 11-tool profile remains available.