> ## Documentation Index
> Fetch the complete documentation index at: https://developer.kyberis.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshoot Agent Setup

> Fix common skill, MCP, token, and access issues.

Use this page when Kyberis skill installation or MCP connection fails.

## Node.js is too old

Both npm setup tools require [Node.js 20 or newer with `npx`](/install/node-npx).

```bash theme={null}
node --version
```

Upgrade Node.js if the version is below `20`.

## Connect Token is Invalid or Expired

Generate a new one-time connect token from [API keys](https://app.kyberis.ai/api-keys) when setup reports:

| Error                        | Meaning                                            |
| ---------------------------- | -------------------------------------------------- |
| `connect_token_not_found`    | The token does not exist.                          |
| `connect_token_used`         | The token was already exchanged.                   |
| `connect_token_revoked`      | The token was revoked.                             |
| `connect_token_expired`      | The token expired.                                 |
| `connect_token_wrong_client` | The token was created for a different client type. |

## Preview Config without Changing Files

Use `--dry-run` to print configuration guidance without updating local client files.

```bash theme={null}
npx -y @kyberis-ai/mcp connect windsurf --token kct_abc123 --dry-run
```

Use `--json` when you need machine-readable connection details.

```bash theme={null}
npx -y @kyberis-ai/mcp connect generic --token kct_abc123 --json
```

## Agent oes not Show Kyberis Tools

Check the client's MCP config file:

| Client   | Config Location                       |
| -------- | ------------------------------------- |
| Codex    | `~/.codex/config.toml`                |
| Cursor   | `~/.cursor/mcp.json`                  |
| Windsurf | `~/.codeium/windsurf/mcp_config.json` |

For Claude, rerun setup with `--dry-run` and verify the printed `claude mcp add` command.

Restart or reload the agent after changing MCP configuration.

## Agent does not Follow the Kyberis Workflow

Check whether the skill is installed:

```bash theme={null}
npx -y @kyberis-ai/agent-skills status codex
npx -y @kyberis-ai/agent-skills status claude
npx -y @kyberis-ai/agent-skills status cursor
npx -y @kyberis-ai/agent-skills status windsurf
```

Refresh installed skills with:

```bash theme={null}
npx -y @kyberis-ai/agent-skills@latest update
```

## API Calls Return `401`

`401` usually means credentials are missing, invalid, or expired. Reconnect MCP with a fresh connect token, or mint a new bearer token from API key credentials.

## API Calls Return `403`

`403` usually means the API key is missing required scopes. Check the response `required_scopes` field, then update or create an API key with those scopes from [API keys](https://app.kyberis.ai/api-keys).

## API Calls Return `429`

Back off and honor `retry_after_seconds` when present. Repeated bad authentication attempts can also trigger `429`.

## Report a Setup Issue

When asking for help, include:

* agent client and version
* setup command used, without secrets
* `request_id`, `run_id`, and `step_id` from any failed Kyberis call
* relevant error code and message