Documentation

Overview

ServAgent is an AI agent tool discovery and optimization platform. It indexes 6,000+ open-source tools from GitHub and provides smart retrieval, multi-protocol format conversion, and a browsable marketplace.

Base URL: https://servagent.ai/api/v1

All responses follow the envelope format: { success, data, meta? }

// Success
{ "success": true, "data": { ... }, "meta": { "total": 2125 } }

// Error
{ "success": false, "error": { "code": "TOOL_NOT_FOUND", "message": "..." } }

Authentication & Access

Most ServAgent endpoints are free and public — no API key needed. A small set of execution endpoints require authentication because they use server-side resources to search the web, fetch URLs, or call external APIs on your behalf.

Public Endpoints (No Auth)

Available to everyone. Rate limit: 100 requests/min for REST, 300/min for MCP.

Protected Endpoints (API Key Required)

These endpoints execute actions using server resources — web searches, URL fetching, and API proxying. An API key prevents abuse and lets us track usage.

How to Get Your API Key

1. Sign in with Google, Apple, or email magic link.
2. Go to the Dashboard to find your API key (format: sk_live_...).
3. Add it to your requests:

# Using Bearer token
curl "https://servagent.ai/api/v1/exec/search?q=hello" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

# In your agent code
headers = {
    "Authorization": "Bearer sk_live_YOUR_KEY",
    "Content-Type": "application/json"
}

Why do exec endpoints need a key? These endpoints use server resources to search the web, fetch pages, and call external APIs on your behalf. Authentication prevents abuse and ensures fair usage. Tool discovery (recommend, list, deploy) stays free forever.

Quick Start

Option A — MCP (Claude Code, 5 seconds)

One line registers ServAgent as an MCP server. Your agent can then call servagent_recommend directly.

claude mcp add --transport http servagent https://servagent.ai/api/mcp

# Now ask your agent: "find me a tool to merge PDFs"
# It will call servagent_recommend and pick the top match.

For Cursor, Windsurf, Cline, Continue, and Claude Desktop, see the deploy cards on the homepage or Pattern 2 below.

Option B — REST API (any language)

Find the right tool for your task and get a ready-to-use definition in 2 calls:

# 1. Recommend tools for a task
curl -X POST https://servagent.ai/api/v1/tools/recommend \
  -H "Content-Type: application/json" \
  -d '{"task": "search the web for news", "maxResults": 3}'

# 2. Get the OpenAI function-calling definition
curl https://servagent.ai/api/v1/deploy/{toolId}/openai

Health Check

curl https://servagent.ai/api/v1/health

// Response
{
  "status": "healthy",
  "version": "0.1.0",
  "timestamp": "2026-04-15T11:00:00.000Z",
  "uptime": 3600,
  "services": { "registry": "up", "recommendations": "up" }
}

List Tools

Returns a paginated list of tools. Supports full-text search and multi-dimensional filtering.

Query Parameters

curl "https://servagent.ai/api/v1/tools?search=github&category=devops&page=1&pageSize=10"

// Response
{
  "success": true,
  "data": [
    {
      "id": "skill-gh-...",
      "name": "act",
      "description": "Run GitHub Actions locally",
      "category": "devops",
      "tags": ["github", "ci", "actions"],
      "provider": { "name": "nektos", "url": "https://github.com/nektos/act", "verified": false },
      "pricing": { "model": "free" },
      "protocols": ["mcp", "openai-functions"]
    }
  ],
  "meta": { "total": 47, "page": 1, "pageSize": 10 }
}

Categories

Get Tool

Returns the full tool definition including parameters, endpoints, GitHub source, and quality scores.

curl https://servagent.ai/api/v1/tools/skill-gh-8b7ed1aa

// Response (abridged)
{
  "success": true,
  "data": {
    "id": "skill-gh-8b7ed1aa",
    "name": "JeecgBoot",
    "description": "...",
    "version": "1.0.0",
    "category": "code-execution",
    "parameters": [],
    "protocols": ["mcp", "openai-functions", "langchain"],
    "source": "github",
    "github": {
      "url": "https://github.com/jeecgboot/JeecgBoot",
      "owner": "jeecgboot",
      "repo": "JeecgBoot",
      "stars": 45848,
      "license": "Apache-2.0"
    },
    "quality_score": 94
  }
}

Recommend Tools

AI-powered tool recommendation based on task description. Uses token-level bidirectional matching with intent expansion — reduces token usage by 401× vs. sending the full registry.

Request Body

curl -X POST https://servagent.ai/api/v1/tools/recommend \
  -H "Content-Type: application/json" \
  -d '{
    "task": "send a Slack message when a GitHub PR is merged",
    "maxResults": 5,
    "preferredProtocols": ["mcp"]
  }'

// Response
{
  "success": true,
  "data": [
    {
      "tool": { "id": "...", "name": "slack-mcp", ... },
      "relevanceScore": 87,
      "reason": "Direct match on communication + slack intent"
    }
  ],
  "meta": { "total": 5, "needsClarification": false, "confidenceScore": 100 }
}

Deploy Tool

Single Tool

Returns the tool definition converted to the target protocol format plus a ready-to-paste usage snippet. Supported protocols: openai anthropic google mcp

curl https://servagent.ai/api/v1/deploy/skill-gh-8b7ed1aa/openai

// Response
{
  "success": true,
  "data": {
    "protocol": "openai",
    "toolId": "skill-gh-8b7ed1aa",
    "toolName": "JeecgBoot",
    "definition": {
      "name": "JeecgBoot",
      "description": "...",
      "parameters": { "type": "object", "properties": {} }
    },
    "installSnippet": "const response = await openai.chat.completions.create({...})"
  }
}

Batch Deploy

Convert up to 50 tools at once to the same protocol. Useful for building a tool registry for your agent.

curl -X POST https://servagent.ai/api/v1/deploy/batch \
  -H "Content-Type: application/json" \
  -d '{
    "toolIds": ["skill-gh-abc", "skill-gh-def"],
    "protocol": "anthropic"
  }'

Protocols

Each protocol produces a different schema format that matches the respective AI SDK:

Bulk Import

Import your own tools into the registry. Max 500 per request. Data is persisted to SQLite and survives restarts.

curl -X POST https://servagent.ai/api/v1/tools/bulk-import \
  -H "Content-Type: application/json" \
  -d '{
    "tools": [{
      "id": "my-tool-1",
      "name": "my-tool",
      "description": "Does something useful",
      "version": "1.0.0",
      "category": "search",
      "tags": ["api", "data"],
      "provider": { "name": "acme", "url": "https://acme.com", "verified": false },
      "parameters": [],
      "pricing": { "model": "free" },
      "endpoints": { "base": "https://acme.com/api" },
      "protocols": ["openai-functions"],
      "createdAt": "2026-01-01T00:00:00Z",
      "updatedAt": "2026-01-01T00:00:00Z"
    }]
  }'

MCP Gateway

ServAgent exposes a standard Model Context Protocol (MCP) server at https://servagent.ai/api/mcp. Connect any MCP-compatible client to access all 6,000+ indexed tools without installing them individually.

The gateway uses JSON-RPC 2.0 over HTTP POST. No auth required.

Supported Methods

# Step 1: Handshake
curl -X POST https://servagent.ai/api/mcp -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'

# Step 2: List tools
curl -X POST https://servagent.ai/api/mcp -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'
# → { "tools": [...100 tools], "nextCursor": "100" }

# Step 3: Next page
curl -X POST https://servagent.ai/api/mcp -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/list","params":{"cursor":"100"}}'

# Step 4: Call a tool
curl -X POST https://servagent.ai/api/mcp -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"skill-gh-8b7ed1aa","arguments":{}}}'

Agent Integration

ServAgent works as a discovery + format relay between your agent and the tools. Two integration patterns:

Pattern 1 — Dynamic Discovery (Recommended)

Call ServAgent at runtime to find the right tool for each task, then inject the schema into your LLM call:

// Node.js example — OpenAI function calling via ServAgent
const BASE = "https://servagent.ai/api/v1";

async function runWithServAgent(userTask: string) {
  // 1. Find the best tool for this task
  const rec = await fetch(`${BASE}/tools/recommend`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ task: userTask, maxResults: 3 }),
  }).then(r => r.json());

  const toolId = rec.data[0].tool.id;

  // 2. Get the OpenAI-compatible schema
  const deploy = await fetch(`${BASE}/deploy/${toolId}/openai`).then(r => r.json());
  const { definition, installSnippet } = deploy.data;

  // 3. Inject into your LLM call
  const response = await openai.chat.completions.create({
    model: "gpt-4o",
    messages: [{ role: "user", content: userTask }],
    tools: [{ type: "function", function: definition }],
  });

  return response;
}

Pattern 2 — MCP Client

Connect any MCP client directly to ServAgent. The gateway exposes all tools as a single MCP server. Compatible with Claude Code, Claude Desktop, Cursor, Cline, and any MCP SDK.

# Claude Code (one line)
claude mcp add --transport http servagent https://servagent.ai/api/mcp

# Claude Desktop config (~/.claude_desktop_config.json or equivalent)
{
  "mcpServers": {
    "servagent": {
      "url": "https://servagent.ai/api/mcp",
      "transport": "http"
    }
  }
}

// Or with MCP TypeScript SDK:
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const client = new Client({ name: "my-agent", version: "1.0.0" });
await client.connect(new StreamableHTTPClientTransport(
  new URL("https://servagent.ai/api/mcp")
));

const { tools } = await client.listTools();
console.log(`Connected to ServAgent: ${tools.length} tools available`);

Pattern 3 — Anthropic Tool Use

import Anthropic from "@anthropic-ai/sdk";

const BASE = "https://servagent.ai/api/v1";
const anthropic = new Anthropic();

// Fetch top tools for the task and get Anthropic-format schemas
const { data: recs } = await fetch(`${BASE}/tools/recommend`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ task: "search the web for news", maxResults: 5 }),
}).then(r => r.json());

const tools = await Promise.all(
  recs.map((r: { tool: { id: string } }) =>
    fetch(`${BASE}/deploy/${r.tool.id}/anthropic`)
      .then(res => res.json())
      .then(d => d.data.definition)
  )
);

const response = await anthropic.messages.create({
  model: "claude-opus-4-6",
  max_tokens: 1024,
  messages: [{ role: "user", content: "What's happening in tech news today?" }],
  tools,
});

Pattern 4 — Python

Works with any Python HTTP client. Public endpoints need no auth; exec endpoints require your API key.

import requests

BASE = "https://servagent.ai/api/v1"
API_KEY = "sk_live_YOUR_KEY"  # from Dashboard → API Keys

# Public — no auth needed
recs = requests.post(f"{BASE}/tools/recommend", json={
    "task": "convert PDF to text",
    "maxResults": 3,
}).json()

for r in recs["data"]:
    print(f'{r["tool"]["name"]} — {r["reason"]}')

# Authenticated — exec endpoints need Bearer token
search = requests.get(f"{BASE}/exec/search", params={
    "q": "latest AI research papers",
    "limit": 5,
}, headers={"Authorization": f"Bearer {API_KEY}"}).json()

for result in search["data"]["results"]:
    print(f'{result["title"]}: {result["url"]}')

# Fetch a URL (also needs auth)
page = requests.get(f"{BASE}/exec/fetch", params={
    "url": "https://example.com",
}, headers={"Authorization": f"Bearer {API_KEY}"}).json()

print(page["data"]["body"][:500])

Pattern 5 — Using Exec Endpoints

Exec endpoints let your agent perform real actions — web search, URL fetch, and free API calls. Search and Fetch require an API key; the public API proxy (/exec/call) is free.

// Node.js — authenticated exec with error handling
const API_KEY = "sk_live_YOUR_KEY";

// Web Search (auth required)
const search = await fetch(`${API}/exec/search?q=MCP+tools&limit=3`, {
  headers: { "Authorization": `Bearer ${API_KEY}` },
}).then(r => r.json());

// URL Fetch (auth required)
const page = await fetch(`${API}/exec/fetch?url=https://docs.example.com`, {
  headers: { "Authorization": `Bearer ${API_KEY}` },
}).then(r => r.json());

// Free Public API Proxy (NO auth needed)
const weather = await fetch(
  `${API}/exec/call?api=open-meteo&params=${encodeURIComponent(
    JSON.stringify({ latitude: 37.7749, longitude: -122.4194 })
  )}`
).then(r => r.json());

console.log(weather.data.current_weather.temperature);

Quick Reference — curl

# Public endpoints — no auth
curl -X POST https://servagent.ai/api/v1/tools/recommend \
  -H "Content-Type: application/json" \
  -d '{"task": "send Slack notifications", "maxResults": 3}'

curl "https://servagent.ai/api/v1/tools?category=communication&limit=10"

# Auth endpoints — add Bearer token
curl "https://servagent.ai/api/v1/exec/search?q=AI+news&limit=5" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

curl "https://servagent.ai/api/v1/exec/fetch?url=https://example.com" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

# Free proxy — no auth
curl "https://servagent.ai/api/v1/exec/call?api=frankfurter&params=%7B%22from%22%3A%22USD%22%2C%22to%22%3A%22EUR%22%7D"

Pipeline — Smart Tool Resolution

The pipeline is the high-performance hot path for agents. It returns the most relevant tools for a query using BM25 + neural embedding search with RRF fusion and LLM reranking. Cache hit: <1ms. Cache miss: <5ms (6000+ tools).

Resolve

curl -X POST https://servagent.ai/api/v1/pipeline/resolve \
  -H "Content-Type: application/json" \
  -d '{"query": "send email via Gmail", "topK": 5, "protocol": "anthropic"}'

// Response
{
  "success": true,
  "data": {
    "tools": [ { "name": "gmail-mcp", "description": "...", ... } ],
    "tokens": { "fullPayload": 165000, "optimized": 412 },
    "cacheHit": false,
    "latencyMs": 2.4,
    "sessionId": "sess_abc123"
  }
}

Feedback

Record whether a resolved tool was successfully used. Closes the data loop for quality scoring.

curl -X POST https://servagent.ai/api/v1/pipeline/feedback \
  -H "Content-Type: application/json" \
  -d '{"sessionId": "sess_abc123", "toolId": "skill-gh-xyz", "success": true, "latencyMs": 320}'

Stats

curl https://servagent.ai/api/v1/pipeline/stats

// Response
{
  "success": true,
  "data": {
    "cache": { "size": 412, "hits": 8931, "misses": 204, "hitRate": 0.978 },
    "telemetry": { "totalCalls": 9135, "circuitsBroken": 0 },
    "toolScores": [ { "toolId": "...", "successRate": 0.97, "totalCalls": 340 } ]
  }
}

Built-in Executable Tools

No installation required. These tools run server-side and return structured results directly. Private/internal hosts are blocked (SSRF protection).

Web Search

curl "https://servagent.ai/api/v1/exec/search?q=model+context+protocol&limit=3" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

// Response
{
  "success": true,
  "data": {
    "query": "model context protocol",
    "results": [
      { "title": "Wikipedia", "url": "https://en.wikipedia.org/...", "snippet": "..." }
    ]
  },
  "meta": { "total": 3 }
}

URL Fetch

curl "https://servagent.ai/api/v1/exec/fetch?url=https://httpbin.org/json" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

// Response
{
  "success": true,
  "data": {
    "url": "https://httpbin.org/json",
    "status": 200,
    "contentType": "application/json",
    "body": { ... }
  }
}

Free Public API Proxy

Proxy to free public APIs — no API key required. Supported api values: open-meteo (weather), frankfurter (currency), ip-api (geolocation), worldtime (timezone), numbersapi (number facts), qrcode (QR generation).

curl "https://servagent.ai/api/v1/exec/call?api=open-meteo&params=%7B%22latitude%22%3A51.5%2C%22longitude%22%3A-0.1%7D"

// Response
{
  "success": true,
  "api": "open-meteo",
  "data": { "current_weather": { "temperature": 18.4, ... } }
}

OpenAPI Spec

Download the full OpenAPI 3.1 spec for ChatGPT GPT Actions or any OpenAPI-compatible client.

curl https://servagent.ai/api/v1/openapi.json

Shadow SDK Telemetry

The Shadow SDK intercepts agent tool calls without changing your code and forwards usage events to ServAgent. Data is aggregated into per-tool success rates, p95 latency, and quality scores visible in the dashboard.

Ingest Event

curl -X POST https://servagent.ai/api/v1/telemetry/ingest \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "skill-gh-8b7ed1aa",
    "success": true,
    "latencyMs": 240,
    "query": "analyze code for bugs",
    "paramKeys": ["source_code", "language"]
  }'

Report

curl https://servagent.ai/api/v1/telemetry/report

// Response
{
  "success": true,
  "data": {
    "pipeline": {
      "totalResolves": 9135,
      "avgTokensSaved": 67199,
      "p95ResolveLatencyMs": 4.1,
      "unmetDemandRate": 0.02,
      "recentUnmetQueries": ["...", "..."]
    },
    "tools": [
      {
        "id": "skill-gh-8b7ed1aa",
        "calls": 340,
        "successRate": 0.97,
        "avgLatencyMs": 180,
        "p95LatencyMs": 410
      }
    ],
    "topChains": [ { "pair": "search→summarize", "count": 47 } ]
  }
}