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	Permission	Description
GET	/mcp/skills	interview:read	List all skills in knowledge base
POST	/mcp/skills/validate	interview:create	Validate skills via pgvector similarity search
POST	/mcp/skills	tenant:update	Add new skill to knowledge base
DELETE	/mcp/skills/:skillId	tenant:delete	Remove skill from knowledge base

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 https://mayaapi.teamcast.ai/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

POST /mcp/skills/validate — Validate Skills

Validate a list of skill names against the knowledge base using pgvector cosine similarity. This is the endpoint the Agno Planner Agent calls internally — fuzzy matching handles typos and aliases like "ReactJS" matching "React".

bash

curl -X POST https://mayaapi.teamcast.ai/api/v1/mcp/skills/validate \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "skills": ["TypeScript", "ReactJS", "Node.js", "Kafak"]
  }'

Response 200

{
  "results": [
    { "input": "TypeScript", "matched": "TypeScript", "similarity": 0.98, "valid": true },
    { "input": "ReactJS",    "matched": "React",      "similarity": 0.91, "valid": true },
    { "input": "Node.js",    "matched": "Node.js",    "similarity": 1.00, "valid": true },
    { "input": "Kafak",      "matched": null,          "similarity": 0.38, "valid": false }
  ]
}

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 https://mayaapi.teamcast.ai/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 →