Troubleshoot agent setup - Kyberis Developer Portal

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.

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 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.

npx -y @kyberis-ai/mcp connect windsurf --token kct_abc123 --dry-run

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

npx -y @kyberis-ai/mcp connect generic --token kct_abc123 --json

Agent does 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:

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:

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.

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

Documentation Index

​Node.js is too old

​Connect token is invalid or expired

​Preview config without changing files

​Agent does not show Kyberis tools

​Agent does not follow the Kyberis workflow

​API calls return 401

​API calls return 403

​API calls return 429

​Report a setup issue