# Install MarkNest for an Agent

This guide is written for an AI agent helping a person install MarkNest. Keep the person in control of local changes and credentials.

## Desired outcome

Connect the user's agent client to MarkNest through one of these adapters:

- **MarkNest Skill 0.2.0** for agents that can load local Skills and run shell commands.
- **`@marknest/mcp-server@0.2.0`** for clients with native MCP support.

Both adapters use the same scoped Public V1 API. Do not install both unless the user has a clear reason to use both interfaces.

## Before changing anything

1. Identify the current agent client and operating system. If either is unknown, ask one short question.
2. Determine whether the client supports local Skills, MCP servers, or both. Prefer the interface the client supports natively.
3. Explain which file or directory you plan to change and ask before changing it.
4. Direct the user to [MarkNest API keys](https://app.marknest.net/api-keys). Do not ask them to paste an API key into chat, logs, source files, or a Git repository.
5. Start with read abilities such as `documents:read`, `folders:read`, `tags:read`, and `rag:read`. Add write abilities only for an explicit workflow.

## Choose an adapter

Choose the **Skill** when the client loads local Skill directories and can run `node` commands. This is usually the best fit for coding agents such as Codex, Claude Code, and OpenCode.

Choose **MCP** when the client provides a native MCP configuration or settings screen. This is usually the best fit for desktop assistants and MCP hosts.

If the client supports both, recommend the Skill for a shell-capable coding workflow and MCP for a client-managed tool workflow. Let the user make the final choice.

## Install the Skill

### Requirements

- A MarkNest Pro or Max account
- A scoped MarkNest API key
- Node.js 22 or newer
- A client-supported local Skill directory

### macOS or Linux

Download the bundle and checksum into a temporary directory:

```sh
curl -fLO https://marknest.net/downloads/marknest-skill-0.2.0.zip
curl -fLO https://marknest.net/downloads/marknest-skill-0.2.0.zip.sha256
shasum -a 256 -c marknest-skill-0.2.0.zip.sha256
unzip marknest-skill-0.2.0.zip
```

Move the extracted `marknest` directory into the Skill directory documented by the current client. Preserve the directory name `marknest`. Do not guess a path when the client exposes its configured Skill location.

### Windows PowerShell

```powershell
Invoke-WebRequest https://marknest.net/downloads/marknest-skill-0.2.0.zip -OutFile marknest-skill-0.2.0.zip
Invoke-WebRequest https://marknest.net/downloads/marknest-skill-0.2.0.zip.sha256 -OutFile marknest-skill-0.2.0.zip.sha256
Get-FileHash marknest-skill-0.2.0.zip -Algorithm SHA256
Get-Content marknest-skill-0.2.0.zip.sha256
Expand-Archive marknest-skill-0.2.0.zip -DestinationPath .
```

Compare the two SHA-256 values before moving the extracted `marknest` directory into the client-supported Skill directory.

### Configure the key

Set `MARKNEST_API_KEY` in the private environment used by the agent. Do not place it in `SKILL.md`, a command committed to shell history, or a tracked environment file.

Restart or reload the agent client if it does not discover newly installed Skills automatically.

## Install the MCP server

### Requirements

- A MarkNest Pro or Max account
- A scoped MarkNest API key
- Node.js 22 or newer
- An MCP client that can start a local stdio server

Confirm the Node.js version before editing configuration:

```sh
node --version
```

Add this server entry through the client's MCP settings or configuration file. Preserve any existing servers in that file.

```json
{
  "mcpServers": {
    "marknest": {
      "command": "npx",
      "args": ["-y", "@marknest/mcp-server@0.2.0"],
      "env": {
        "MARKNEST_API_KEY": "mk_your_api_key"
      }
    }
  }
}
```

Prefer the client's protected environment or secret storage when it supports one. If the client requires the key in a local configuration file, explain that limitation, confirm the file is private and ignored by version control, then let the user enter the key locally.

Restart or reload the client after saving the MCP configuration.

## Verify read-only access

Finish with one read-only check. Do not create, update, publish, share, or delete content during installation.

For the Skill, run:

```sh
node scripts/marknest.mjs documents list
```

Run the command from the installed `marknest` Skill directory with `MARKNEST_API_KEY` available in the private process environment.

For MCP, ask the client to list MarkNest documents or perform a semantic search. Confirm that MarkNest tools are visible before invoking one.

Report only whether the check succeeded, the number of returned items, and any non-sensitive error. Never print the API key or full request headers.

## Troubleshooting

- **Node.js is missing or older than 22:** stop and guide the user to install a current Node.js release. Do not silently replace their runtime.
- **The Skill is not discovered:** confirm the extracted folder is named `marknest`, confirm it is in the client's active Skill directory, then reload the client.
- **MCP tools are not visible:** validate the JSON without deleting other entries, confirm the package name and version, then reload the client.
- **Authentication fails:** confirm that `MARKNEST_API_KEY` is available to the agent process and that the key has not expired. Do not display it.
- **Permission is denied:** return to [API key settings](https://app.marknest.net/api-keys) and add only the missing read ability.
- **The checksum does not match:** delete the downloaded ZIP and checksum, download both again from `marknest.net`, and stop if the mismatch continues.

## Reference links

- [Human setup page](https://marknest.net/features/agents)
- [MCP setup page](https://marknest.net/features/mcp)
- [Public API documentation](https://marknest.net/docs/api)
- [OpenAPI document](https://marknest.net/openapi.yaml)
- [LLM index](https://marknest.net/llms.txt)