LVNGDocs
API ReferenceSDKslvng.ai

MCP Servers API

Register and manage Model Context Protocol (MCP) servers that provide tools and capabilities to AI agents. Supports stdio, SSE, and WebSocket transport types. Monitor server health, refresh tool lists, and manage configurations. All endpoints require JWT authentication and are rate-limited to 100 requests per minute.

Base path: /api/v2/mcps

MCP Server CRUD

Register, list, retrieve, update, and delete MCP servers. Soft-delete is used to preserve historical data.

POST/api/v2/mcpsAuthenticated

Register a new MCP server. The server starts in 'registered' status with an empty tool list that is populated on first connection or refresh.

Body Parameters

namestringrequired

Display name for the MCP server.

descriptionstring

Description of the server and its tools.

typestringrequired

Transport type: "stdio", "sse", or "websocket".

configobject

Transport configuration.

config.commandstring

Command to launch (required for stdio type).

config.argsstring[]

Command arguments (for stdio type).

config.urlstring

Server URL (required for sse/websocket types).

config.headersobject

Custom headers (for sse/websocket types).

config.envobject

Environment variables for the server process.

metadataobject

Arbitrary metadata.

tagsstring[]

Tags for categorization.

workspaceIdstring

Workspace to scope the server to.

isEnabledboolean

Whether the server is enabled. Defaults to true.

Request

cURL
400">curl -X 400">POST https:400">class="text-zinc-500">//api.lvng.ai/api/v2/mcps \
  -H 400">class="text-emerald-400">"Authorization: Bearer YOUR_API_KEY" \
  -H 400">class="text-emerald-400">"Content-Type: application/json" \
  -d '{
    400">class="text-emerald-400">"name": 400">class="text-emerald-400">"Web Search MCP",
    400">class="text-emerald-400">"description": 400">class="text-emerald-400">"Provides web search and scraping tools",
    400">class="text-emerald-400">"400">type": 400">class="text-emerald-400">"sse",
    400">class="text-emerald-400">"config": {
      400">class="text-emerald-400">"url": 400">class="text-emerald-400">"https:400">class="text-zinc-500">//mcp.myserver.com/sse",
      400">class="text-emerald-400">"headers": { 400">class="text-emerald-400">"x-api-key": 400">class="text-emerald-400">"server-key-123" }
    },
    400">class="text-emerald-400">"tags": [400">class="text-emerald-400">"search", 400">class="text-emerald-400">"web"]
  }'

Response 201

{
  400">class="text-emerald-400">"success": true,
  400">class="text-emerald-400">"mcp": {
    400">class="text-emerald-400">"id": 400">class="text-emerald-400">"mcp_abc123",
    400">class="text-emerald-400">"user_id": 400">class="text-emerald-400">"a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
    400">class="text-emerald-400">"name": 400">class="text-emerald-400">"Web Search MCP",
    400">class="text-emerald-400">"description": 400">class="text-emerald-400">"Provides web search and scraping tools",
    400">class="text-emerald-400">"400">type": 400">class="text-emerald-400">"sse",
    400">class="text-emerald-400">"config": {
      400">class="text-emerald-400">"url": 400">class="text-emerald-400">"https:400">class="text-zinc-500">//mcp.myserver.com/sse",
      400">class="text-emerald-400">"headers": { 400">class="text-emerald-400">"x-api-key": 400">class="text-emerald-400">"server-key-123" }
    },
    400">class="text-emerald-400">"status": 400">class="text-emerald-400">"registered",
    400">class="text-emerald-400">"is_enabled": true,
    400">class="text-emerald-400">"tools": [],
    400">class="text-emerald-400">"tags": [400">class="text-emerald-400">"search", 400">class="text-emerald-400">"web"],
    400">class="text-emerald-400">"created_at": 400">class="text-emerald-400">"2026-04-01T12:00:00.000Z"
  }
}
GET/api/v2/mcpsAuthenticated

List MCP servers with search, filtering, and pagination.

Query Parameters

searchstring

Search by name or description.

typestring

Filter by transport type: stdio, sse, websocket.

statusstring

Filter by status: registered, connected, error.

workspaceIdstring

Filter by workspace.

isEnabledboolean

Filter by enabled status.

limitinteger

Maximum results. Defaults to 50.

offsetinteger

Pagination offset.

Request

cURL
400">curl -X 400">GET 400">class="text-emerald-400">"https:400">class="text-zinc-500">//api.lvng.ai/api/v2/mcps?400">type=sse&status=connected" \
  -H 400">class="text-emerald-400">"Authorization: Bearer YOUR_API_KEY"

Response 200

{
  400">class="text-emerald-400">"success": true,
  400">class="text-emerald-400">"mcps": [
    {
      400">class="text-emerald-400">"id": 400">class="text-emerald-400">"mcp_abc123",
      400">class="text-emerald-400">"name": 400">class="text-emerald-400">"Web Search MCP",
      400">class="text-emerald-400">"400">type": 400">class="text-emerald-400">"sse",
      400">class="text-emerald-400">"status": 400">class="text-emerald-400">"connected",
      400">class="text-emerald-400">"is_enabled": true,
      400">class="text-emerald-400">"tags": [400">class="text-emerald-400">"search", 400">class="text-emerald-400">"web"],
      400">class="text-emerald-400">"created_at": 400">class="text-emerald-400">"2026-04-01T12:00:00.000Z"
    }
  ],
  400">class="text-emerald-400">"total": 1,
  400">class="text-emerald-400">"limit": 50,
  400">class="text-emerald-400">"offset": 0
}
GET/api/v2/mcps/:idAuthenticated

Get full MCP server details including configuration, tools, and status.

Path Parameters

idstringrequired

UUID of the MCP server.

Request

cURL
400">curl -X 400">GET https:400">class="text-zinc-500">//api.lvng.ai/api/v2/mcps/mcp_abc123 \
  -H 400">class="text-emerald-400">"Authorization: Bearer YOUR_API_KEY"

Response 200

{
  400">class="text-emerald-400">"success": true,
  400">class="text-emerald-400">"mcp": {
    400">class="text-emerald-400">"id": 400">class="text-emerald-400">"mcp_abc123",
    400">class="text-emerald-400">"name": 400">class="text-emerald-400">"Web Search MCP",
    400">class="text-emerald-400">"description": 400">class="text-emerald-400">"Provides web search and scraping tools",
    400">class="text-emerald-400">"400">type": 400">class="text-emerald-400">"sse",
    400">class="text-emerald-400">"config": { 400">class="text-emerald-400">"url": 400">class="text-emerald-400">"https:400">class="text-zinc-500">//mcp.myserver.com/sse" },
    400">class="text-emerald-400">"status": 400">class="text-emerald-400">"connected",
    400">class="text-emerald-400">"is_enabled": true,
    400">class="text-emerald-400">"tools": [
      { 400">class="text-emerald-400">"name": 400">class="text-emerald-400">"web_search", 400">class="text-emerald-400">"description": 400">class="text-emerald-400">"Search the web" },
      { 400">class="text-emerald-400">"name": 400">class="text-emerald-400">"scrape_url", 400">class="text-emerald-400">"description": 400">class="text-emerald-400">"Scrape a URL" }
    ],
    400">class="text-emerald-400">"tags": [400">class="text-emerald-400">"search", 400">class="text-emerald-400">"web"],
    400">class="text-emerald-400">"last_connected_at": 400">class="text-emerald-400">"2026-04-01T12:00:00.000Z",
    400">class="text-emerald-400">"created_at": 400">class="text-emerald-400">"2026-04-01T12:00:00.000Z"
  }
}
PUT/api/v2/mcps/:idAuthenticated

Update MCP server configuration. Allowed fields: name, description, config, metadata, tags, isEnabled.

Path Parameters

idstringrequired

UUID of the MCP server.

Body Parameters

namestring

Updated name.

descriptionstring

Updated description.

configobject

Updated transport config.

metadataobject

Updated metadata.

tagsstring[]

Updated tags.

isEnabledboolean

Enable or disable the server.

Request

cURL
400">curl -X 400">PUT https:400">class="text-zinc-500">//api.lvng.ai/api/v2/mcps/mcp_abc123 \
  -H 400">class="text-emerald-400">"Authorization: Bearer YOUR_API_KEY" \
  -H 400">class="text-emerald-400">"Content-Type: application/json" \
  -d '{
    400">class="text-emerald-400">"isEnabled": false,
    400">class="text-emerald-400">"tags": [400">class="text-emerald-400">"search", 400">class="text-emerald-400">"web"]
  }'

Response 200

{
  400">class="text-emerald-400">"success": true,
  400">class="text-emerald-400">"mcp": {
    400">class="text-emerald-400">"id": 400">class="text-emerald-400">"mcp_abc123",
    400">class="text-emerald-400">"name": 400">class="text-emerald-400">"Web Search MCP",
    400">class="text-emerald-400">"is_enabled": false,
    400">class="text-emerald-400">"tags": [400">class="text-emerald-400">"search", 400">class="text-emerald-400">"web"],
    400">class="text-emerald-400">"updated_at": 400">class="text-emerald-400">"2026-04-01T14:00:00.000Z"
  }
}
DELETE/api/v2/mcps/:idAuthenticated

Soft-delete an MCP server. Sets deleted_at, disables it, and sets status to 'deleted'.

Path Parameters

idstringrequired

UUID of the MCP server.

Request

cURL
400">curl -X 400">DELETE https:400">class="text-zinc-500">//api.lvng.ai/api/v2/mcps/mcp_abc123 \
  -H 400">class="text-emerald-400">"Authorization: Bearer YOUR_API_KEY"

Response 200

{
  400">class="text-emerald-400">"success": true,
  400">class="text-emerald-400">"message": 400">class="text-emerald-400">"MCP server deleted"
}

Server Operations

List tools, check server health, and refresh tool catalogs.

GET/api/v2/mcps/:id/toolsAuthenticated

List all tools provided by an MCP server.

Path Parameters

idstringrequired

UUID of the MCP server.

Request

cURL
400">curl -X 400">GET https:400">class="text-zinc-500">//api.lvng.ai/api/v2/mcps/mcp_abc123/tools \
  -H 400">class="text-emerald-400">"Authorization: Bearer YOUR_API_KEY"

Response 200

{
  400">class="text-emerald-400">"success": true,
  400">class="text-emerald-400">"mcpId": 400">class="text-emerald-400">"mcp_abc123",
  400">class="text-emerald-400">"mcpName": 400">class="text-emerald-400">"Web Search MCP",
  400">class="text-emerald-400">"status": 400">class="text-emerald-400">"connected",
  400">class="text-emerald-400">"lastConnected": 400">class="text-emerald-400">"2026-04-01T12:00:00.000Z",
  400">class="text-emerald-400">"tools": [
    { 400">class="text-emerald-400">"name": 400">class="text-emerald-400">"web_search", 400">class="text-emerald-400">"description": 400">class="text-emerald-400">"Search the web for information" },
    { 400">class="text-emerald-400">"name": 400">class="text-emerald-400">"scrape_url", 400">class="text-emerald-400">"description": 400">class="text-emerald-400">"Scrape content 400">from a URL" }
  ],
  400">class="text-emerald-400">"count": 2
}
POST/api/v2/mcps/:id/healthAuthenticated

Check MCP server health. For servers with a URL, performs an HTTP ping. For stdio servers, uses a last-connection heuristic (healthy if connected within 5 minutes).

Path Parameters

idstringrequired

UUID of the MCP server.

Request

cURL
400">curl -X 400">POST https:400">class="text-zinc-500">//api.lvng.ai/api/v2/mcps/mcp_abc123/health \
  -H 400">class="text-emerald-400">"Authorization: Bearer YOUR_API_KEY"

Response 200

{
  400">class="text-emerald-400">"success": true,
  400">class="text-emerald-400">"mcpId": 400">class="text-emerald-400">"mcp_abc123",
  400">class="text-emerald-400">"name": 400">class="text-emerald-400">"Web Search MCP",
  400">class="text-emerald-400">"healthy": true,
  400">class="text-emerald-400">"status": 400">class="text-emerald-400">"connected",
  400">class="text-emerald-400">"statusCode": 200,
  400">class="text-emerald-400">"responseTime": 89,
  400">class="text-emerald-400">"checkedAt": 400">class="text-emerald-400">"2026-04-01T14:00:00.000Z"
}
POST/api/v2/mcps/:id/refreshAuthenticated

Refresh the tool list by fetching from the MCP server's /tools endpoint. Falls back to cached tools if the server is unreachable.

Path Parameters

idstringrequired

UUID of the MCP server.

Request

cURL
400">curl -X 400">POST https:400">class="text-zinc-500">//api.lvng.ai/api/v2/mcps/mcp_abc123/refresh \
  -H 400">class="text-emerald-400">"Authorization: Bearer YOUR_API_KEY"

Response 200

{
  400">class="text-emerald-400">"success": true,
  400">class="text-emerald-400">"mcpId": 400">class="text-emerald-400">"mcp_abc123",
  400">class="text-emerald-400">"name": 400">class="text-emerald-400">"Web Search MCP",
  400">class="text-emerald-400">"message": 400">class="text-emerald-400">"Tools fetched 400">from server",
  400">class="text-emerald-400">"tools": [
    { 400">class="text-emerald-400">"name": 400">class="text-emerald-400">"web_search", 400">class="text-emerald-400">"description": 400">class="text-emerald-400">"Search the web for information" },
    { 400">class="text-emerald-400">"name": 400">class="text-emerald-400">"scrape_url", 400">class="text-emerald-400">"description": 400">class="text-emerald-400">"Scrape content 400">from a URL" },
    { 400">class="text-emerald-400">"name": 400">class="text-emerald-400">"extract_links", 400">class="text-emerald-400">"description": 400">class="text-emerald-400">"Extract all links 400">from a page" }
  ],
  400">class="text-emerald-400">"count": 3,
  400">class="text-emerald-400">"refreshedAt": 400">class="text-emerald-400">"2026-04-01T14:00:00.000Z"
}