# Use marketplace skills in Windsurf

Source: https://opvs.ai/docs/guides/use-skills-in-your-ai-tool/windsurf

> Connect Windsurf to the OPVS marketplace through the OPVS MCP server, then find, read, install and call skills.

You will connect Windsurf to the OPVS MCP server, then find, read and use marketplace skills from a normal conversation. How the parts fit together is on [How it works](https://opvs.ai/docs/guides/use-skills-in-your-ai-tool/how-it-works.md).

**You need:** Node.js 18 or newer, and an OPVS workspace (your workspace admin approves your access).

## 1. Install and sign in

```bash
npm install -g @opvs-ai/cli @opvs-ai/mcp
opvs auth request -e <your-workspace-admin-email>
```

Your admin receives an approval email. Once approved, the token is saved locally and the MCP server uses it.

## 2. Add the OPVS server to Windsurf

In Windsurf, open **Settings → Cascade → MCP servers → View raw config** (the file is `~/.codeium/windsurf/mcp_config.json`) and add:

```json
{ "mcpServers": { "opvs": { "command": "opvs-mcp" } } }
```

Refresh the server list; `opvs` should show its tools.

## 3. Check it works

Ask Windsurf:

> Use tool_search to find an OPVS skill for cleaning tracking parameters out of URLs.

You should get ranked packages, for example `@di-atomic/url-utils`, each with a `telemetry_signal`.

## 4. Read a skill (nothing to install)

> Use tool_read on @di-atomic/url-utils and follow its recipe to clean these links: …

`tool_read` returns the skill's `SKILL.md` and a list of its reference files; the agent can read any of them with `tool_read(name, path="references/…")`. That is all a guidance skill needs.

## 5. Use a skill that calls a service

1. **Install it on your workspace.** A workspace admin does this once, either in the OPVS dashboard (**Skills**, at `app.opvs.ai/dashboard/marketplace`) or by asking the agent to call `tool_install` with the package `id` from `tool_search`. If the package needs permissions or credentials, they are granted during install; missing ones leave it `pending`.
2. **Learn its methods:** `tool_help(name="@vendor/name", section="methods")`.
3. **Call it:** `tool_call(skill="@vendor/name", method="…", params={…})`. Read the `_guidance` in the reply before acting on the data.

`tool_list_installed` shows what your workspace has installed.

## Skill files in your project (known issue)

The skills CLI can also write a skill as native files for Windsurf (`opvs-skills install @vendor/name --runtime windsurf --dest .`). On 8 Nov 2026 this fails for marketplace packages (`no bundle recorded (manifest-only package)`), so use `tool_read` and `tool_call` through the MCP server until it is fixed.

## Troubleshooting

You see

Cause

Fix

`Not authenticated`

no approved token

run `opvs auth request -e <admin-email>` and have the admin approve

the tool is "not enabled" or unknown

Windsurf has the server's tools switched off

enable the `opvs` tools in Windsurf's MCP settings

`opvs-mcp: command not found`

the global install failed

re-run `npm install -g @opvs-ai/mcp` on its own and read the error

`422` from `tool_install`

a required permission was not granted

grant the permissions listed in the reply's `_guidance`

`403` from `tool_install`

you are not a workspace admin

ask your admin to install it

`tool_call` says the skill is not installed

it is not installed on this workspace

install it first (step 5)

More detail on the server itself: [MCP server](https://opvs.ai/docs/tools/mcp-server.md).