Glosswork

Install Glosswork

This page is written for an AI agent. If you are a person, paste this page’s address into your agent and ask it to set Glosswork up for you.

Agent: follow the steps in order. Where a step says Ask your human, stop, put the question to your human in words, and wait for the answer. Ask even when you think you already know the answer from context. Do not skip ahead.

1. What Glosswork is

Glosswork is a shared place where your human’s agents and team keep structured information: object types, fields, records, comments, and a full history of who changed what. You design the structure yourself, through MCP tools, from a plain description of what your human wants to keep track of, and every type, field, and option carries a description written for the next agent that reads it. You can build and add freely, but you cannot delete a field or a type on your own: destructive schema changes become proposals a human approves in the Glosswork web UI.

2. Hosted or self-hosted

Ask your human: “Do you want Glosswork to run it for you (hosted), or do you want to run it yourself on a computer you control (self-hosted)? Self-hosting needs Docker and takes about ten minutes.”

Ask this and wait for the answer, even if earlier messages make self-hosting look likely. A port number or container name your human mentioned is not an answer to this question.

3. Check what you can do

You need to run shell commands on the computer that will host Glosswork.

Ask your human: “Should I install Glosswork on this computer?” Ask this and wait for the answer, even if you are already running on a computer that has Docker. If they name a different computer, the commands are the same, but they have to be run there, and the MCP address in step 8 changes. This page covers only the case where the agent and Glosswork run on the same computer. If they need other people to reach it over a network, tell them that needs HTTPS and a reverse proxy, which this page does not cover, and stop.

Commands below are for macOS or Linux. On Windows, use PowerShell, use the one-line form where one is given, and type curl.exe wherever a command says curl.

4. Check Docker

Run:

docker version --format '{{.Server.Version}}'

Check that no Glosswork container exists already:

docker ps -a --filter name=^glosswork$ --format '{{.Names}} {{.Status}}'
docker volume ls --filter name=^glosswork-data$ --format '{{.Name}}'

If either prints anything, stop and ask your human what it is. It may hold their data. Never remove an existing container or volume.

Check that port 8000 is free:

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8000/

000 means the port is free. Any other number means something is already using it: pick another port, such as 8010, check it the same way, and use that number everywhere this page says 8000. Change both numbers in the -p option and the one in GW_BASE_URL, but not the :8000 on the container side of -p.

From here on, this page calls three values your install values: the address http://127.0.0.1:8000 (with your port if you changed it), the container name glosswork, and the volume name glosswork-data. If your human asked for different names, use theirs wherever this page says glosswork for the container or glosswork-data for the volume. Step 8 carries these values across a restart.

5. Choose the first administrator

Ask your human:

  1. “What email address should your Glosswork administrator account use?”
  2. “Choose a password of at least 12 characters, or I can generate one for you.” To generate one, run openssl rand -base64 18.

If you generate the password, show it to your human once, before you start Glosswork, so they can save it. Tell your human to save the email and password in their password manager now. They use them to sign in to the web UI. Do not write the password into any file.

6. Start Glosswork

Replace you@example.com and CHOSEN-PASSWORD with the answers from step 5, then run:

docker volume create glosswork-data
docker run -d --name glosswork --restart unless-stopped \
  -p 127.0.0.1:8000:8000 \
  -v glosswork-data:/data \
  -e GW_BASE_URL=http://127.0.0.1:8000 \
  -e GW_COOKIE_SECURE=false \
  -e GW_BOOTSTRAP_ADMIN_EMAIL=you@example.com \
  -e GW_BOOTSTRAP_ADMIN_PASSWORD='CHOSEN-PASSWORD' \
  docker.io/glosswork/glosswork:latest

The same docker run on one line, for Windows PowerShell:

docker run -d --name glosswork --restart unless-stopped -p 127.0.0.1:8000:8000 -v glosswork-data:/data -e GW_BASE_URL=http://127.0.0.1:8000 -e GW_COOKIE_SECURE=false -e GW_BOOTSTRAP_ADMIN_EMAIL=you@example.com -e GW_BOOTSTRAP_ADMIN_PASSWORD='CHOSEN-PASSWORD' docker.io/glosswork/glosswork:latest

What each setting does:

Setting Why
-p 127.0.0.1:8000:8000 Reachable from this computer only.
-v glosswork-data:/data Everything Glosswork stores lives in this Docker volume. Removing the volume deletes the workspace.
GW_BASE_URL The address agents use. Glosswork accepts MCP requests only for this exact host and port, so use 127.0.0.1, not localhost, everywhere below.
GW_COOKIE_SECURE=false Lets the browser sign-in work over plain http:// on this computer.
GW_BOOTSTRAP_ADMIN_EMAIL, GW_BOOTSTRAP_ADMIN_PASSWORD Create the first administrator on the first start. Later starts leave the account alone.

The image is about 500 MB, so the first pull takes a minute or two. Wait until Glosswork is ready:

curl -fsS --retry 30 --retry-connrefused --retry-all-errors --retry-delay 2 http://127.0.0.1:8000/readyz

It prints a response and exits 0 when ready. While Glosswork starts, it may also print curl: (52) Empty reply from server one or more times. That is normal: it keeps retrying, and it has worked when it exits 0. If it exits non-zero, run docker logs glosswork. Every log line is JSON, and a configuration error names the variable at fault. Show the error to your human.

7. Get an access token

Agents authenticate with a personal access token with admin scope, which you need to create object types. Who creates it depends on your harness.

Claude Code, Claude Desktop and VS Code: your human creates it, in the web page. The token then goes from their clipboard into the installer’s prompt in step 8 and never passes through this chat, your shell output, or a command line. Do not mint one yourself for these three. Do this when step 8 tells you to, not before. Tell your human:

  1. Open http://127.0.0.1:8000 (your install address) and sign in with the email and password from step 5.
  2. Open Setup. Under Personal access tokens, in Mint a new token, enter the name claude-code (or claude-desktop, or vscode), choose the scope admin, and choose Mint token.
  3. Choose Copy to clipboard. The token is shown once. Do not paste it into this chat. Paste it only where step 8 asks for it.

If your human pasted the token into this chat by mistake, revoke it (below) and have them mint another.

Every other harness: mint it yourself. Capture it in the variable TOKEN and check that it works:

TOKEN=$(docker exec glosswork python -m glosswork.admin mint-token --name gemini-cli --scope admin --quiet)
curl -sS -X POST http://127.0.0.1:8000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"install-check","version":"0"}}}'

A response containing "instructions" means the token works. An error whose message says the request carried no credential, or that the token is unknown, means the header is wrong. A response of Invalid Host header means the address does not match GW_BASE_URL exactly.

Mint once, and register in the same command. Many agent shells start a fresh shell for every command, so TOKEN is gone by the next command. If yours does, do not run the lines above on their own. Run the mint, the check, and your step 8 registration as one command, joined with && so registration runs only when the check passes. Step 8 shows this for Gemini CLI.

If your human is running the commands for you (step 3), they run the mint-token line without TOKEN=$( and ), and paste the printed token into the configuration file in step 8, not into this chat.

If a token is lost, mangled, printed into chat, or left over from a failed attempt, revoke it. It stays valid until someone does. Tell your human which token it was by its name. There are two ways:

glosswork.admin has no command to revoke a single token. Its revoke command removes a person’s access to an object type, not a token. Its set-password revokes every token and signed-in session the account holds, so use it only as a last resort.

8. Connect your harness

The server facts, for any harness:

Claude Code and Claude Desktop connect through the Glosswork connection kit, at https://github.com/glosswork/glosswork-connect. The kit asks your human for the address and the token in its own prompt, so nobody edits a configuration file and the token stays out of this chat. Every other harness uses a snippet under “Any other MCP client”.

Claude Code

You install the plugin. Your human gives it the address and the token.

  1. Add the kit’s marketplace and install the plugin. Neither command needs a token:

    claude plugin marketplace add glosswork/glosswork-connect
claude plugin install glosswork@glosswork --scope user

    Each prints Successfully and exits 0. The install then says two required settings are not set. That is expected. Your human sets them next.

  2. Tell your human to do the following in a Claude Code session, and to do it themselves, because the token must not pass through this chat:

    • Run /plugin configure glosswork@glosswork.
    • Enter the workspace address http://127.0.0.1:8000/mcp (your install address, ending in /mcp, spelled exactly as in your install values).
    • Mint the token as step 7 describes, name claude-code, scope admin, and paste it into the “Access token” field. While the field has focus, Claude Code shows the last six characters of what was pasted. That is normal.

  3. The plugin loads in a new session. Give your human the message in “After registering” below, then have them start a new Claude Code session and run /mcp. The server plugin:glosswork:glosswork should show as connected.

The plugin stores the token in Claude Code’s secure storage (the macOS Keychain, or a credentials file in Claude Code’s configuration directory when the Keychain refuses it), keeps only the address in settings.json, and sends X-Agent-Label: claude-code on every call. --scope user makes Glosswork available in every project on this computer, which means every project can reach an admin token to this workspace.

To undo it, run claude plugin uninstall glosswork@glosswork. Then revoke the token by its name claude-code in Setup (step 7).

Claude Desktop

Claude Desktop’s custom connectors connect from Anthropic’s cloud, so they cannot reach a Glosswork running on this computer. The kit’s Claude Desktop extension can. It is a small file your human installs, and it asks for the address and the token. You cannot run commands from Claude Desktop, so your human does every step, and you give them each one.

  1. Tell your human to build the extension. It needs git, Node.js with npm, bash, and network access:

    git clone https://github.com/glosswork/glosswork-connect
bash glosswork-connect/mcpb/build.sh

    It prints bundle: and the path of glosswork.mcpb. The kit measured this build on macOS only. On Windows, run it in Git Bash.

  2. Tell your human to open Claude Desktop, go to Settings, then Extensions, then Advanced settings, choose Install Extension, and pick that glosswork.mcpb file.

  3. Claude Desktop may warn that the extension is unsigned or from an unknown developer. That is expected: the kit does not sign it yet. Your human continues.

  4. Claude Desktop asks for two values, and nothing else. Tell your human to enter the address http://127.0.0.1:8000/mcp (your install address, ending in /mcp), and to mint the token as step 7 describes, name claude-desktop, scope admin, and paste it into the token field. The token goes into the operating system’s secure storage, and the extension passes it to its proxy through an environment variable, so it does not show in the process list.

  5. Have your human quit Claude Desktop completely and reopen it, then start a new chat. Give them the message in “After registering” below first.

Spell the address exactly as your install values do. A workspace answers only for its own host:port, so localhost where the workspace says 127.0.0.1 fails with Invalid Host header and status 421, which looks nothing like a token problem. Do not change the address to a network address such as http://192.168.1.20:8000/mcp: on a plain http:// address that is not on this computer, the token crosses the network in clear text, and this page covers only one computer.

Any other MCP client

These harnesses have no kit installer yet. Except for VS Code, each of these snippets holds the token in plain text in a file or a command, so tell your human which file it is in, and that it must not be committed to a repository or shared. Mint the token yourself, as step 7 describes, using the harness name in --name. Commands use $TOKEN from step 7, in the same command that minted it. In the files, replace gw_pat_REPLACE_ME with the token.

Cursor

Add to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json in the project:

{
  "mcpServers": {
    "glosswork": {
      "url": "http://127.0.0.1:8000/mcp",
      "headers": {
        "Authorization": "Bearer gw_pat_REPLACE_ME"
      }
    }
  }
}

Cursor also accepts "Bearer ${env:GLOSSWORK_TOKEN}" if your human prefers to keep the token in an environment variable.

VS Code

VS Code prompts for the token when it starts the server, so the token is never written into the file and never passes through this chat. Your human mints it the way step 7 describes for Claude Code, with the name vscode and scope admin. Do not mint it yourself.

Add to .vscode/mcp.json in the project. To make Glosswork available in every project instead, have your human run MCP: Open User Configuration from the Command Palette and put the same content there:

{
  "servers": {
    "glosswork": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp",
      "headers": {
        "Authorization": "Bearer ${input:glosswork-token}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "glosswork-token",
      "description": "Glosswork access token",
      "password": true
    }
  ]
}

The top-level key is servers, not mcpServers. Have your human run MCP: List Servers, start glosswork, choose to trust it when VS Code asks, and paste the token into the prompt. VS Code stores what they paste for later starts.

Codex CLI

Add to ~/.codex/config.toml:

[mcp_servers.glosswork]
url = "http://127.0.0.1:8000/mcp"
http_headers = { "Authorization" = "Bearer gw_pat_REPLACE_ME" }

Or, to keep the token in an environment variable that is set wherever Codex starts, run codex mcp add glosswork --url http://127.0.0.1:8000/mcp --bearer-token-env-var GLOSSWORK_TOKEN. Start a new Codex session afterwards.

Windsurf

Windsurf is now called Devin Desktop. Its documentation puts the file at ~/.config/devin/mcp_config.json (or $XDG_CONFIG_HOME/devin/mcp_config.json; on Windows %APPDATA%\devin\mcp_config.json) and says these MCP settings apply to the legacy Cascade agent. An older install keeps the file at ~/.codeium/windsurf/mcp_config.json. Use whichever of the two already exists on this computer, and if neither does, use the first. Your human can also open it from the ... menu of the Cascade panel, using the Open MCP config file icon. Add:

{
  "mcpServers": {
    "glosswork": {
      "serverUrl": "http://127.0.0.1:8000/mcp",
      "headers": {
        "Authorization": "Bearer gw_pat_REPLACE_ME"
      }
    }
  }
}

Then restart Windsurf, or use the toggle next to glosswork in the MCPs section of the Cascade panel’s ... menu.

Gemini CLI

Mint, check, and register in one command:

TOKEN=$(docker exec glosswork python -m glosswork.admin mint-token --name gemini-cli --scope admin --quiet) &&
curl -sS -X POST http://127.0.0.1:8000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"install-check","version":"0"}}}' \
  | grep -q '"instructions"' &&
gemini mcp add --transport http \
  --header "Authorization: Bearer $TOKEN" \
  glosswork http://127.0.0.1:8000/mcp

It exits 0 when the token works and Glosswork is registered. If it exits non-zero, nothing was registered, but a token may have been minted: revoke gemini-cli (step 7) before you try again.

With no --scope, Gemini CLI uses project scope, its default. It has no separate local scope. Project scope writes .gemini/settings.json in this directory, with the token in plain text, and Glosswork is available only when Gemini CLI starts here. Tell your human not to commit that file. In a folder your human has not trusted, Gemini CLI does not load .gemini/settings.json and does not connect to any MCP server. gemini mcp list shows when this is the cause: it lists glosswork as Disabled and warns that the folder is untrusted. Gemini CLI asks your human whether to trust a folder the first time it starts there. If they chose not to, have them type /permissions trust inside Gemini CLI, choose to trust the folder, and start a new session. Use project scope unless your human asks for something else. --scope user writes ~/.gemini/settings.json instead, which makes the admin token available in every directory. To undo, run gemini mcp remove glosswork --scope <the scope you used>.

To edit a file instead, use .gemini/settings.json in this directory, or ~/.gemini/settings.json for every directory. Note the key is httpUrl, not url:

{
  "mcpServers": {
    "glosswork": {
      "httpUrl": "http://127.0.0.1:8000/mcp",
      "headers": {
        "Authorization": "Bearer gw_pat_REPLACE_ME"
      }
    }
  }
}

Start a new Gemini CLI session afterwards.

A client not listed

Most clients accept this shape. Some name the address key url, serverUrl, or httpUrl, and some need "type": "http" or "streamable-http", so check the client’s own documentation:

{
  "mcpServers": {
    "glosswork": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp",
      "headers": {
        "Authorization": "Bearer gw_pat_REPLACE_ME"
      }
    }
  }
}

After registering

Most harnesses load MCP servers only when a session starts. A new session remembers nothing from this one, so the message your human gives it must carry your install values. If your harness needs a restart, tell your human before it happens, and give them this message with your real values filled in, to paste into the new session:

Continue the Glosswork install at step 9 of PAGE-ADDRESS. Glosswork is at http://127.0.0.1:PORT, in the container CONTAINER-NAME, with its data in the volume VOLUME-NAME.

Replace PAGE-ADDRESS with this page’s address, and PORT, CONTAINER-NAME, and VOLUME-NAME with your install values from step 4. Give the actual values even if they are the defaults (8000, glosswork, glosswork-data).

If you are the new session: use the address, container, and volume from that message wherever steps 9 and 10 name them. They override the defaults on this page.

When the Glosswork tools are available to you, you will see tools such as describe_capabilities, list_object_types, and create_object_type. If they do not appear, check that the address is exactly your install address followed by /mcp, such as http://127.0.0.1:8000/mcp, and the header is exactly Authorization: Bearer gw_pat_....

9. Ask your human what they want to keep track of

This is the point of everything above.

  1. Call describe_capabilities. It is Glosswork’s manual: field types, the operators each one allows, key rules, and limits.
  2. Ask your human: “What do you want to keep track of?”
  3. From their answer, design and create the object type with create_object_type: fields with real types, select options with descriptions, and relations where two things are genuinely different things. Write every description for the agent that reads it next, not for a human skimming a form.
  4. Show your human what you built, descriptions included, and offer to enter their first few records.

Things to tell your human along the way:

10. Keep it safe