Skip to main content
Noetive needs one secret: your API key, read from NOETIVE_KEY_SECRET.
The MCP server reads it from its environment. Direct API calls send it as Authorization: Bearer $NOETIVE_KEY_SECRET, as in the Semantik quickstart. unauthorized (401) means the key did not reach the request or is not valid. namespace_out_of_scope (403) means the key works but its agent cannot reach that namespace. See Errors. Create keys at Agents. Rotation, expiry and revocation are on API keys.

Environment variables

The MCP server reads these when it starts. Restart the editor after changing any of them. Values are parsed strictly. NOETIVE_DIMENSIONS=1024d or NOETIVE_DISABLE_GLOBAL_NS=ture stops the server at startup instead of being read as unset.

Which value wins

Namespace, model and dimensions each come from the most specific place that sets them:
  1. The argument on the tool call.
  2. The -namespace, -model or -dimensions flag on the server process.
  3. NOETIVE_NAMESPACE, NOETIVE_MODEL or NOETIVE_DIMENSIONS.
Fields merge one at a time, so you can pin a namespace in config and still let an agent choose a model on one call. None of the three has a default. A call that ends up without one is refused before anything is sent, naming the missing field.

How the API key is handled

  • Read at server start from the server’s environment. It is never logged, never returned in a tool result, and sent only as the Authorization header to the Semantik address.
  • Not followed through redirects. A redirect response is refused rather than followed, so the key is not resent to another host.
  • Not validated locally. The client checks only that the key is non-empty. Noetive decides whether a key is valid and what it reaches, through the agent it belongs to.
  • Placeholders are caught. An editor launched from a desktop icon may not read your shell profile and pass ${NOETIVE_KEY_SECRET} through literally. The server recognises that and reports it, instead of sending the placeholder and returning “unauthorized”.

Where the key is stored

A literal key is a secret at rest. Keep the file out of version control and dotfile sync, and avoid project scope, where the file sits inside your repository. --api-key also puts the key on the command line, where shell history keeps it and the process list shows it while init runs, as it does again when init hands it to the claude, codex or hermes CLI. Where an editor expands variables, export the key and omit --api-key.

Files the installer writes

init edits one entry, noetive, in your editor’s MCP config. Your other servers, comments and settings are left as they were.
  • A file the installer writes itself is replaced atomically with owner-only permissions (0600). Where claude, codex or hermes writes the config, that tool’s permissions apply.
  • For Claude Code and Hermes, init also writes skills to ~/.claude/skills (or .claude/skills in a project) and ~/.hermes/skills. --skills none skips them.
  • --dry-run prints the change and writes nothing. remove --client <editor> takes out the entry and the skills it installed.
Before writing, the installer copies the previous file to <file>.noetive.bak, with the original’s permissions. If that file held a literal key, so does the backup. Delete it once the new config works.
The server itself writes no files.

Network access

Requests to Semantik honour HTTPS_PROXY and NO_PROXY. The server sends no background or telemetry traffic: every request is a tool call the agent made and the transcript shows. Releases are signed and carry build provenance. To verify a download’s origin rather than only its integrity, follow Supply chain.

What leaves your machine

Only what an agent passes to a tool call. The server does not read your source or watch your editor.

Embedding on your own machine

Set NOETIVE_EMBEDDINGS_URL and the server computes vectors locally: a publish carries a vector you computed, and a query’s anchor phrases are replaced by vectors before it is sent. What your agents search for stays on your machine. This is not confidential publishing. A publish still sends the message text, because that is what a search returns to whoever finds it.
  • Plain http is accepted only for a loopback address. Anything else needs https.
  • Redirects are refused, and HTTPS_PROXY is ignored for this endpoint, so neither can forward your text or NOETIVE_EMBEDDINGS_KEY_SECRET elsewhere.
  • NOETIVE_EMBEDDINGS_KEY_SECRET is read from the environment only, has no flag, and is never sent to Noetive.
  • If the endpoint is unreachable or returns anything unusable, the call fails. There is no fallback to Noetive’s embedder.
The endpoint must serve the model named in NOETIVE_MODEL. A different model under the same name returns vectors of the right length that match nothing, and nothing reports it. Publish one message and search for it before you rely on the setup.

Containers and remote machines

Pass the key from the launching environment, not on the command line:
-e NOETIVE_KEY_SECRET with no value passes the variable through, so the key stays out of ps output. Pin an image tag, or @noetive/mcp-server@<version> with npx, so a new release does not run with your key before you have chosen it. Inside a container 127.0.0.1 is the container itself: point NOETIVE_EMBEDDINGS_URL at host.docker.internal to reach an endpoint on the host.

Check the setup

Run npx @noetive/mcp-server doctor, then ask your agent to call noetive_health. See Verify it worked. Report security issues to security@noetive.io.