API Reference

MCP Skills

Vector-indexed skill knowledge base for AI-powered skill validation and similarity search.

The MCP (Model Context Protocol) skill endpoints expose the pgvector-backed skill knowledge base. The Agno Planner Agent uses these to validate skills submitted in interview requests and find semantically related skills via cosine similarity.

Endpoints

Method	Endpoint	Description
GET	/mcp/skills	List all skills in knowledge base
GET	/mcp/skills/search	Semantic similarity search
GET	/mcp/skills/:id	Get skill details
POST	/mcp/skills	Add new skill (ADMIN only)

GET /mcp/skills — List Skills

Returns all skills seeded in the knowledge base. The knowledge base ships with 18 pre-seeded skills across categories: Frontend, Backend, Database, Cloud, and Mobile.

bash

curl http://localhost:3009/api/v1/mcp/skills \
  -H "Authorization: Bearer <jwt>"

Response 200

[
  {
    "id": "skill-uuid",
    "name": "TypeScript",
    "category": "BACKEND",
    "description": "Statically typed superset of JavaScript",
    "aliases": ["TS", "typescript"],
    "relatedSkills": ["JavaScript", "Node.js", "React"]
  },
  {
    "id": "skill-uuid-2",
    "name": "React",
    "category": "FRONTEND",
    "description": "JavaScript library for building user interfaces",
    "aliases": ["ReactJS", "React.js"],
    "relatedSkills": ["TypeScript", "Next.js", "Redux"]
  }
]

Category	Skills
FRONTEND	React, Next.js, Vue.js, Angular
BACKEND	Node.js, TypeScript, Python, Go, Java, NestJS
DATABASE	PostgreSQL, MongoDB, Redis, MySQL
CLOUD	AWS, GCP, Azure, Docker, Kubernetes
MOBILE	React Native, Flutter, Swift, Kotlin

GET /mcp/skills/search — Similarity Search

Perform a semantic similarity search using pgvector cosine similarity. This is how the Agno agent validates submitted skills — fuzzy matching handles typos and aliases like "ReactJS" matching "React".

bash

curl "http://localhost:3009/api/v1/mcp/skills/search?q=typescript+react&limit=5" \
  -H "Authorization: Bearer <jwt>"

Query Param	Type	Description
q	string	Skill name(s) to search for (required)
limit	number	Max results per query term (default: 5)
threshold	number	Minimum similarity score 0–1 (default: 0.6)

Response 200

{
  "results": [
    {
      "query": "typescript",
      "matches": [
        {
          "skill": { "id": "skill-uuid", "name": "TypeScript", "category": "BACKEND" },
          "similarity": 0.98,
          "isExact": true
        },
        {
          "skill": { "id": "skill-uuid-2", "name": "JavaScript", "category": "BACKEND" },
          "similarity": 0.72,
          "isExact": false
        }
      ]
    },
    {
      "query": "react",
      "matches": [
        {
          "skill": { "id": "skill-uuid-3", "name": "React", "category": "FRONTEND" },
          "similarity": 0.99,
          "isExact": true
        }
      ]
    }
  ]
}

POST /mcp/skills — Add Skill

Add a new skill to the knowledge base. The embedding is automatically generated using the configured embedding model and stored in the pgvector column.

bash

curl -X POST http://localhost:3009/api/v1/mcp/skills \
  -H "Authorization: Bearer <admin-jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Rust",
    "category": "BACKEND",
    "description": "Systems programming language with memory safety guarantees",
    "aliases": ["rust-lang"],
    "relatedSkills": ["C++", "Go", "WebAssembly"]
  }'

Response 201

{
  "id": "skill-uuid-new",
  "name": "Rust",
  "category": "BACKEND",
  "description": "Systems programming language with memory safety guarantees",
  "embeddingDimension": 1536,
  "createdAt": "2024-01-15T10:00:00.000Z"
}

Seed the Knowledge Base

bash

# Seed all 18 default skills with embeddings
npx ts-node prisma/seed-skills.ts

The Agno agent uses a similarity threshold of 0.6. Skills with similarity below this threshold are flagged as unrecognized and included in the missingFields webhook payload if validation fails.

Was this page helpful?

Previous← Admin Monitoring

NextHealth Checks →