Using the /server/{type} Endpoint

Overview

The /server/\{type\} endpoint provides programmatic access to MCP server configurations. This endpoint allows you to retrieve server metadata, including server names, descriptions, URLs, and configuration details for any available MCP server.

Endpoint Details

• URL: POST /server/\{type\}
• Method: POST
• Authentication: Not required (public endpoint)
• Content-Type: application/json

Purpose

This endpoint is useful for:

• Discovering available MCP servers
• Getting server configuration details
• Integrating MCP servers into external applications
• Building dynamic server selection interfaces
• Retrieving server URLs and metadata programmatically

Request Format

URL Parameters

Parameter	Type	Required	Description
type	string	Yes	The server type identifier (kebab-case)

Valid Server Types

Type	Server Name	Description
revenue	Revenue Server	Revenue attribution and conversion analysis
sales-prioritization	Sales Prioritization Server	High-priority account identification
data-activation	Data Activation Server	Unified visitor and company data analysis
data-activation-companies	Data Activation Companies Server	Company/account analysis
data-activation-visitors	Data Activation Visitors Server	Visitor behavior analysis
intent-signal	Intent Signal Server	Intent signal tracking
marketing-influence	Marketing Influence Server	Marketing attribution analysis
report	Report Server	General reporting
outbound	Outbound Server	Outbound campaign analysis

Response Format

Success Response (200 OK)

{
  "data": {
    "type": "mcp",
    "server_label": "revenue-server",
    "server_description": "# Milestone Terminology\nThe milestone tool contains flags...",
    "server_url": "https://ask.sonalabs.com/mcp/revenue",
    "require_approval": "never"
  }
}

Response Fields

Field	Type	Description
type	string	Always "mcp" - indicates this is an MCP server
server_label	string	Human-readable server name
server_description	string	Detailed server instructions and documentation (Markdown format)
server_url	string	Full URL to access the MCP server
require_approval	string	Approval requirement level ("never", "always", "conditional")

Error Response (404 Not Found)

{
  "error": "Server not found",
  "message": "Server sales-prioritizationn does not exist"
}

Usage Examples

Example 1: Get Revenue Server Configuration

Request:

curl -X POST https://ask.sonalabs.com/server/revenue \
  -H "Content-Type: application/json"

Response:

{
  "data": {
    "type": "mcp",
    "server_label": "revenue-server",
    "server_description": "# Milestone Terminology\nThe milestone tool contains flags that indicate milestone types...",
    "server_url": "https://ask.sonalabs.com/mcp/revenue",
    "require_approval": "never"
  }
}

Example 2: Get Sales Prioritization Server

Request:

curl -X POST https://ask.sonalabs.com/server/sales-prioritization \
  -H "Content-Type: application/json"

Response:

{
  "data": {
    "type": "mcp",
    "server_label": "sales-prioritization-server",
    "server_description": "You are a Sales Prioritization analyst specializing in high-priority accounts...",
    "server_url": "https://ask.sonalabs.com/mcp/sales-prioritization",
    "require_approval": "never"
  }
}

Example 3: Get Outbound Server Configuration

Request:

curl -X POST https://ask.sonalabs.com/server/outbound \
  -H "Content-Type: application/json"

Response:

{
  "data": {
    "type": "mcp",
    "server_label": "outbound-server",
    "server_description": "You are an Outbound Campaign analyst specializing in engagement data...",
    "server_url": "https://ask.sonalabs.com/mcp/outbound",
    "require_approval": "never"
  }
}

Example 4: Handle Invalid Server Type

Request:

curl -X POST https://ask.sonalabs.com/server/invalid-server \
  -H "Content-Type: application/json"

Response:

{
  "error": "Server not found",
  "message": "Server invalid-server does not exist"
}

JavaScript/TypeScript Example

async function getServerConfig(serverType) {
  try {
    const response = await fetch(
      `https://ask.sonalabs.com/server/${serverType}`,
      {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
        },
      },
    );

    if (!response.ok) {
      throw new Error(`Server not found: ${serverType}`);
    }

    const data = await response.json();
    return data.data;
  } catch (error) {
    console.error("Error fetching server config:", error);
    throw error;
  }
}

// Usage
const revenueServer = await getServerConfig("revenue");
console.log("Server URL:", revenueServer.server_url);
console.log("Server Label:", revenueServer.server_label);

Python Example

import requests

def get_server_config(server_type):
    """Get MCP server configuration."""
    url = f"https://ask.sonalabs.com/server/{server_type}"

    try:
        response = requests.post(url, headers={'Content-Type': 'application/json'})
        response.raise_for_status()
        return response.json()['data']
    except requests.exceptions.HTTPError as e:
        print(f"Error: Server {server_type} not found")
        raise
    except Exception as e:
        print(f"Error fetching server config: {e}")
        raise

# Usage
revenue_server = get_server_config('revenue')
print(f"Server URL: {revenue_server['server_url']}")
print(f"Server Label: {revenue_server['server_label']}")

PHP Example

<?php

function getServerConfig($serverType) {
    $url = "https://ask.sonalabs.com/server/{$serverType}";

    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);

    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($httpCode !== 200) {
        throw new Exception("Server not found: {$serverType}");
    }

    $data = json_decode($response, true);
    return $data['data'];
}

// Usage
try {
    $revenueServer = getServerConfig('revenue');
    echo "Server URL: " . $revenueServer['server_url'] . "\n";
    echo "Server Label: " . $revenueServer['server_label'] . "\n";
} catch (Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";
}

Common Use Cases

1. Dynamic Server Discovery

Build a UI that dynamically discovers and displays available MCP servers:

const serverTypes = [
  "revenue",
  "sales-prioritization",
  "data-activation-companies",
  "outbound",
  "intent-signal",
];

async function discoverServers() {
  const servers = [];

  for (const type of serverTypes) {
    try {
      const config = await getServerConfig(type);
      servers.push({
        type,
        label: config.server_label,
        url: config.server_url,
        description: config.server_description.split("\n")[0], // First line
      });
    } catch (error) {
      console.warn(`Server ${type} not available`);
    }
  }

  return servers;
}

2. Server Selection Interface

Create a dropdown or selection interface based on available servers:

async function buildServerSelector() {
  const servers = await discoverServers();

  const select = document.createElement("select");
  servers.forEach((server) => {
    const option = document.createElement("option");
    option.value = server.url;
    option.textContent = server.label;
    option.dataset.description = server.description;
    select.appendChild(option);
  });

  return select;
}

3. Configuration Caching

Cache server configurations to reduce API calls:

class ServerConfigCache {
  constructor() {
    this.cache = new Map();
    this.ttl = 3600000; // 1 hour
  }

  async get(serverType) {
    const cached = this.cache.get(serverType);

    if (cached && Date.now() - cached.timestamp < this.ttl) {
      return cached.config;
    }

    const config = await getServerConfig(serverType);
    this.cache.set(serverType, {
      config,
      timestamp: Date.now(),
    });

    return config;
  }
}

const configCache = new ServerConfigCache();
const revenueServer = await configCache.get("revenue");

4. Server Health Check

Check if servers are available:

async function checkServerHealth(serverType) {
  try {
    const config = await getServerConfig(serverType);
    return {
      available: true,
      url: config.server_url,
      label: config.server_label,
    };
  } catch (error) {
    return {
      available: false,
      error: error.message,
    };
  }
}

// Check multiple servers
const healthChecks = await Promise.all([
  checkServerHealth("revenue"),
  checkServerHealth("sales-prioritization"),
  checkServerHealth("outbound"),
]);

Best Practices

1. Error Handling

Always handle potential errors when calling the endpoint:

try {
  const config = await getServerConfig(serverType);
  // Use config
} catch (error) {
  if (error.message.includes("not found")) {
    console.error("Invalid server type");
  } else {
    console.error("Network or server error");
  }
}

2. Type Validation

Validate server types before making requests:

const VALID_SERVER_TYPES = [
  "revenue",
  "sales-prioritization",
  "data-activation",
  "data-activation-companies",
  "data-activation-visitors",
  "intent-signal",
  "marketing-influence",
  "report",
  "outbound",
];

function isValidServerType(type) {
  return VALID_SERVER_TYPES.includes(type);
}

async function getServerConfigSafe(serverType) {
  if (!isValidServerType(serverType)) {
    throw new Error(`Invalid server type: ${serverType}`);
  }
  return await getServerConfig(serverType);
}

3. Caching

Implement caching to reduce unnecessary API calls:

const configCache = new Map();

async function getCachedServerConfig(serverType) {
  if (configCache.has(serverType)) {
    return configCache.get(serverType);
  }

  const config = await getServerConfig(serverType);
  configCache.set(serverType, config);
  return config;
}

4. Parsing Server Description

The server_description field contains Markdown. Parse it appropriately:

import marked from "marked";

async function getServerInfo(serverType) {
  const config = await getServerConfig(serverType);

  return {
    label: config.server_label,
    url: config.server_url,
    descriptionHtml: marked.parse(config.server_description),
    descriptionText: config.server_description,
  };
}

Server Type Naming Convention

Server types follow kebab-case naming:

• Class name: RevenueServer → Type: revenue
• Class name: SalesPrioritizationServer → Type: sales-prioritization
• Class name: DataActivationCompaniesServer → Type: data-activation-companies

The conversion is automatic based on the server class name.

Troubleshooting

Issue: 404 Server Not Found

Cause: Invalid server type or server class doesn't exist

Solution:

• Verify the server type is spelled correctly (kebab-case)
• Check the list of valid server types above
• Ensure the server class exists in app/Mcp/Servers/

Issue: Empty server_description

Cause: Server class has no instructions defined

Solution: Check the server class for the $instructions property

Issue: Wrong server URL

Cause: Application base URL is not configured correctly

Solution: Verify APP_URL in your .env file

Support

For issues or questions about the /server/\{type\} endpoint:

1. Check the server type spelling and format
2. Verify the server exists in the codebase
3. Review error messages for specific issues
4. Consult the MCP Servers Overview documentation