Getting started — reach the AI Employee catalog from your agent¶

In this tutorial you'll connect a coding agent to the OPVS AI Employee catalog and make it read a real employee profile. By the end of this page your agent will be answering questions about the catalog from inside your IDE, with no dashboard involved.

It takes about five minutes and costs nothing. Everything here uses the two public, unauthenticated methods, so you do not need an account or a token to finish it.

What you'll need¶

Node.js 18 or newer
An MCP-capable agent host: Claude Code, Cursor, Windsurf, or anything that reads .mcp.json

Step 1 — install the package¶

First, install the scoped MCP wrapper from public npm. It is a small server that exposes the catalog to your agent as typed tools.

npm install -g @opvs-ai/mcp-employees
# → added 12 packages in 3s

The package pins its SDK exactly, so it pulls a matching @opvs-ai/skills-sdk with it. If the install fails, run it again on its own rather than inside a longer npm install -g list: that form is all-or-nothing and aborts every package when any one of them fails to resolve.

Step 2 — register it with your agent¶

Add the server to your host's MCP configuration. In Claude Code that is .mcp.json at the root of your project.

{
  "mcpServers": {
    "opvs-employees": {
      "command": "opvs-mcp-employees",
      "env": { "OPVS_API_URL": "https://api.opvs.ai" }
    }
  }
}

There is no token in that config. The two methods used in this tutorial are public, and adding a credential you do not need is a habit worth avoiding.

Step 3 — ask your agent to browse the catalog¶

Restart your agent host so it picks up the new server, then ask it something the catalog can answer:

Search the OPVS employee catalog for an SDR and tell me what skills the profile lists.

The agent calls the catalog search method, then reads the single profile it picked. You should see a real role, real skills, and a real price band come back — the same rows the public site serves.

Step 4 — confirm it is really the live catalog¶

Ask for the total. The catalog held 113 published profiles when this page was written, so a number in that range tells you the agent reached production rather than an empty local stub.

curl -s "https://api.opvs.ai/api/v1/employees/published?limit=1"
# → {"profiles": [{"slug": "ai-sdr", "role": "AI SDR"}], "total": 113}

If that returns total: 0, your agent is pointed at a different host: check OPVS_API_URL.

Where to go next¶

You have read-only access to the catalog. To act on it — list a team, hire, or equip a profession — your agent needs a brand-pinned token. The how-to guide covers that, and the reference documents all seven methods with their error codes.

One thing to know before you go further: hiring requires an active service plan on the brand. Until one is attached, the hire method returns a structured 403 naming the cap it hit. Reading the catalog and listing a team are unaffected.

OPVS Developer Docs

Getting started