Administration

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude

Purpose

Configure MCP connectors so mentors can call external MCP tools and return results inside the chat.

MCP Tab Overview

• Featured connectors: prebuilt/default (some open-source) you can enable
• Custom connectors: define your own endpoint and authentication

Add a Custom Connector

1. Go to MCP → Custom Connectors → Add.
2. Fill the fields:
   • Image (optional)
   • Name
   • URL (connector/server URL)
   • Description (optional)
   • Transport type
   • Authentication method:
     • None
     • API Key
   • Token type for the header (e.g., Bearer, Basic, Token)
   • Token value
3. Click Connect to save.
   • The connector appears in your list.
4. You can enable/disable any connector.
   • Disabling prevents mentors from using that MCP server in replies.

Example: Connect an MCP Server with API Key

1. In the MCP provider, copy the Access URL and Access Token.
2. In MCP → Custom Connectors, set:
   • Name: e.g., Workflow MCP
   • URL: paste the access URL
   • Auth: API Key
   • Token type: Bearer
   • Token value: paste the token
3. Click Connect.
   • The connector is added and can be toggled on/off.

Using MCP in Chat (Demo Flow)

1. Grab a project ID from your MCP workspace.
2. Ask the mentor, for example:
   • “List the workflows in the project <PROJECT_ID>.”
3. The mentor lists active workflows (e.g., FAQ, webhook test, etc.).
4. Run a workflow, for example:
   • “Execute the FAQ workflow and tell me: How do I reset my password?”
5. The mentor includes your question in the workflow request body and returns the answer from the MCP server.

Result

Your mentors can call enabled MCP connectors to list resources and execute workflows, returning MCP-sourced answers directly in the conversation.

MCP Servers

Model Context Protocol (MCP) servers that expose APIs as tools for AI agents like Claude Code and Cursor.

Available Servers

Authentication

All servers require a Platform API Key:

1. Log into the Admin panel
2. Navigate to Platform Settings > API Keys
3. Create and copy your API key

Analytics Server

Get insights about learning activity, mentor usage, and costs.

Description (for MCP Setup)

The iblai-analytics MCP server enables AI agents to access detailed analytics about mentor-student interactions, conversation patterns, topic analysis, sentiment tracking, and cost reporting. This server provides comprehensive insights into learning activity, mentor usage, user engagement metrics, LLM costs, and platform effectiveness. Key features include: learner analytics, content analytics, message and session tracking, topic analysis, financial reporting, and time-based metrics.

Setup

{
  "mcpServers": {
    "iblai-analytics": {
      "url": "https://your-instance.com/mcp/analytics/",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Api-Token YOUR_API_KEY"
      }
    }
  }
}

Example Queries

Once configured, ask your AI assistant:

• "How many users are active in the acme platform?"
• "What topics are students asking about most?"
• "Show me conversation trends for the last month"
• "What are the LLM costs broken down by mentor?"
• "Which students have the most chat messages?"
• "What's the average course grade?"

Working Examples

Basic Health Check and User Info

# Health check
ping()  # Returns: "2026-01-12T23:08:47.008677+00:00"

# Get current user
get_current_user()  # Returns: "ibl_user"

# Get user platforms
get_user_platforms()
# Returns: "User: ibl_user\nMember of platforms: ibl, main, ...\nAdmin of platforms: ibl, main, ..."

# Count users in platform
count_users_in_platform(platform="ibl")  # Returns: 8

Learner Analytics

# Get learner analytics for a specific user
get_learner_analytics(
    username="ibl_user",
    platform_key="ibl"
)
# Returns: User summary with time spent, enrollments, credentials, etc.

# Get learner list for a platform
get_learner_list(
    platform_key="ibl",
    limit=5
)
# Returns: Paginated list of learners with metrics

# Get detailed learner information
get_learner_details(
    username="ibl_user",
    platform_key="ibl"
)
# Returns: Consolidated learner analytics across catalog, mentor, and credential data

Content Analytics

# Get content analytics (requires platform_key)
get_content_analytics(
    metric="courses",
    platform_key="ibl"
)
# Returns: Course analytics with enrollments, time spent, completion rates, etc.

# Get detailed content information
get_content_details(
    content_id="course-v1:Academy+S-IB-50+v1",
    metric="course",
    platform_key="ibl"
)
# Returns: Detailed course information with learner breakdowns

Important Notes:

• Most analytics endpoints require platform_key parameter
• get_web_analytics_time_spent_per_user requires admin user privileges
• Use metric parameter to specify content type: "course", "courses", "program", "programs", "pathway", "pathways", "skill", or "skills"

Search Server

⚠️ Temporarily Disabled: The Search server is currently disabled while we clean up naming conventions. It will be re-enabled in a future update.

Search for courses and mentors in the catalog.

Description (for MCP Setup)

The iblai-search MCP server enables AI agents to search for courses, programs, pathways, and mentors in the learning catalog. This server provides global search capabilities for discovering educational content and AI mentors. Key features include: catalog search across courses, programs, pathways and skills; mentor search to find AI tutors by topic or expertise; and course recommendations based on user preferences.

Setup

{
  "mcpServers": {
    "iblai-search": {
      "url": "https://your-instance.com/mcp/search/",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Api-Token YOUR_API_KEY"
      }
    }
  }
}

Example Queries

• "Find courses about machine learning"
• "Search for mentors that teach Python"
• "What courses would you recommend for a beginner?"
• "Show me the most popular courses in the catalog"

Working Examples

Health Check

# Health check
ping()  # Returns: "2026-01-12T23:14:26.318962+00:00"

Catalog Search

# Search catalog for courses, programs, pathways, skills
get_catalog_search(
    query="test",
    limit=5
)
# Returns: Search results with courses, programs, pathways
# Includes facets for filtering (topics, subjects, tags, etc.)

Mentor Search

# Search for mentors (requires platform_key for authenticated requests)
get_mentor_search(
    query="test",
    limit=5,
    platform_key="ibl"
)
# Returns: List of mentors matching the query with metadata

Important Notes:

• get_mentor_search requires platform_key parameter for authenticated requests
• Use platform_key or tenant parameter (both serve the same purpose)
• Search results include pagination information

Recommendations

# Get course recommendations
get_recommendations(
    platform_key="ibl",
    limit=3
)
# Returns: Personalized course recommendations based on RAG search
# Can specify recommendation_type: "mentors", "courses", "programs", "resources", "pathways"

Agent Create Server

Create and manage AI mentors, including CRUD operations, forking, and configuration.

Description (for MCP Setup)

The iblai-agent-create MCP server enables AI agents to create, configure, and manage AI mentors. This server provides full mentor lifecycle management including creation from templates, settings configuration, and document training. Key features include: create mentors from templates; configure LLM settings (provider, model, temperature); manage display settings and feature flags; train mentors with documents, URLs, or text content; and update mentor prompts and permissions.

Setup

{
  "mcpServers": {
    "iblai-agent-create": {
      "url": "https://your-instance.com/mcp/agent-create/",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Api-Token YOUR_API_KEY"
      }
    }
  }
}

Example Queries

• "Create a new mentor for data science"
• "List all mentors in the platform"
• "Update mentor settings for mentor ID 123"
• "Fork mentor ID 456 with new name"
• "Show me available mentor templates"
• "What categories are available for mentors?"

Working Examples

Health Check

# Health check
ping()  # Returns: "2026-01-12T22:57:37.066570+00:00"

Get Mentor Settings

# Retrieve mentor settings
get_mentor_settings(
    org="ibl",
    user_id="ibl_user",
    mentor="ad2be335-5afa-4a9e-9298-8273b3d94e10"
)
# Returns: Complete mentor configuration including:
# - Display settings (theme, colors, images)
# - LLM configuration (provider, model, temperature)
# - Feature flags (image generation, web browsing, code interpreter)
# - Prompts (system, proactive, study mode)
# - Visibility and permissions

Create Mentor from Template

# Create a new mentor from a template
post_mentor_with_settings(
    org="ibl",
    user_id="ibl_user",
    template_name="ai-mentor",
    new_mentor_name="test-mentor-123"
)
# Returns: Created mentor object with unique_id, settings, and configuration
# Optional parameters: display_name, description, system_prompt, llm_provider, etc.

Update Mentor Settings

# Update existing mentor settings
put_mentor_settings(
    org="ibl",
    user_id="ibl_user",
    mentor="ad2be335-5afa-4a9e-9298-8273b3d94e10",
    mentor_description="Updated description for testing"
)
# Returns: Updated mentor settings object
# Can update: mentor_name, display_name, system_prompt, llm_provider,
# enable_image_generation, enable_web_browsing, categories, types, subjects, etc.

Train Documents

# Train a document directly (for smaller documents)
post_retriever_train(
    org="ibl",
    user_id="ibl_user",
    pathway="ad2be335-5afa-4a9e-9298-8273b3d94e10",  # Use mentor_id as pathway
    url="https://example.com/test-document"
)
# Returns: {"detail": "Document trained successfully"}

# Train a document through worker process (for larger documents)
post_train_document(
    org="ibl",
    user_id="ibl_user",
    type="url",
    pathway="ad2be335-5afa-4a9e-9298-8273b3d94e10",  # Use mentor_id as pathway
    url="https://example.com/test"
)
# Returns: Task confirmation or error message

Important Notes:

• For post_train_document and post_retriever_train, use the mentor_id as the pathway parameter
• The pathway parameter must be a valid mentor unique ID (UUID format)
• post_train_document supports multiple types: "file", "url", "text" (for Wikipedia), etc.
• If URL is not accessible, you'll get: "We couldn't reach the website. It may be offline or blocking access."

Agent Chat Server

Have conversations with AI mentors. Requires specifying which mentor to use.

Description (for MCP Setup)

The iblai-agent-chat MCP server enables AI agents to have conversations with configured AI mentors. This server acts as a bridge to interact with specialized mentors that have been trained on specific topics or documents. The mentor is specified via the X-Mentor-Unique-Id header, and responses are based on the mentor's system prompt, LLM configuration, and trained knowledge base.

Setup

{
  "mcpServers": {
    "iblai-agent": {
      "url": "https://your-instance.com/mcp/agent-chat/",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Api-Token YOUR_API_KEY",
        "X-Mentor-Unique-Id": "YOUR_MENTOR_ID"
      }
    }
  }
}

Example Queries

• "Explain how photosynthesis works"
• "Help me understand quadratic equations"
• "What are the key events of World War II?"
• "Can you review this code and suggest improvements?"

Working Examples

Chat with Mentor

# Get a response from a mentor
get_mentor_response(
    prompt="hello"
)
# Returns: "Hello! How can I assist you today?"

# More complex query
get_mentor_response(
    prompt="Can you explain machine learning in simple terms?"
)
# Returns: Detailed explanation from the mentor based on their configuration

Important Notes:

• The mentor is specified via the X-Mentor-Unique-Id header in the MCP server configuration
• The mentor's response depends on their system prompt, LLM configuration, and any trained documents
• Simple prompts like "hello" work well for testing connectivity

Full Configuration

To use all available servers together:

{
  "mcpServers": {
    "iblai-analytics": {
      "url": "https://your-instance.com/mcp/analytics/",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Api-Token YOUR_API_KEY"
      }
    },
    "iblai-agent": {
      "url": "https://your-instance.com/mcp/agent-chat/",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Api-Token YOUR_API_KEY",
        "X-Mentor-Unique-Id": "YOUR_MENTOR_ID"
      }
    },
    "iblai-agent-create": {
      "url": "https://your-instance.com/mcp/agent-create/",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Api-Token YOUR_API_KEY"
      }
    },
    "iblai-search": {
      "url": "https://your-instance.com/mcp/search/",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Api-Token YOUR_API_KEY"
      }
    }
  }
}

Note: The iblai-search server excludes personalized search tools (personalized mentor search and personalized catalog search).

Save this to:

• Claude Code: ~/.claude/claude_desktop_config.json or .mcp.json in your project
• Cursor: Add to Settings > Features > MCP Servers

Tool Generation and Endpoints

This section documents the endpoints used by each MCP server and how tool names are generated.

Tool Name Generation Format

Tool names follow the pattern: {HTTP_METHOD}_{usable_name}

Where:

• {HTTP_METHOD}: The HTTP method in lowercase (e.g., get, post, put, patch, delete)
• {usable_name}: Derived from the URL pattern name with transformations:
  • Hyphens converted to underscores
  • Redundant prefixes removed (apis_, ai_analytics_, ai_mentor_, v2_, trigram_)
  • Section prefixes removed (for analytics: overview_, audience_, etc.)
  • Common words abbreviated (e.g., completion → compl, enrollment → enroll)

Example: URL pattern name ai_mentor_orgs_users_mentor_with_settings → Tool name post_mentor_with_settings

iblai-agent (Mentor Chat Server)

Custom Tool (not auto-generated from endpoints):

Note: This is a custom tool that directly calls the LLM service, not generated from an API endpoint.

iblai-agent-create (Agent Create Server)

Endpoints (auto-generated from API patterns):

Tool Name Generation Examples:

• mentor-with-settings → post_mentor_with_settings (hyphen → underscore, method prefix added)
• mentor-settings → get_mentor_settings / put_mentor_settings (different methods create different tools)
• ai_index_orgs_users_documents_train → post_train_document (prefixes removed, simplified)

iblai-search (Search Server)

Endpoints (auto-generated from search patterns, excluding personalized):

Excluded Tools (personalized endpoints):

• get_personalized_mentors - Personalized mentor recommendations
• get_personalized_catalog_search - Personalized catalog search

Tool Name Generation:

• URL pattern names are cleaned by removing redundant prefixes
• Only GET methods are included (only_get=True in registration)
• Personalized endpoints are explicitly filtered out

Custom Tools (not auto-generated):

• ping_search: Health check

iblai-analytics (Analytics Server)

Endpoints (auto-generated from /api/analytics/ namespace):

All endpoints under /api/analytics/ are automatically included. Examples:

Tool Name Generation:

• URL pattern names are cleaned by removing redundant prefixes and applying abbreviations
• Only GET methods are included (only_get=True in registration)
• All endpoints starting with /api/analytics/ are automatically included

Custom Tools (not auto-generated):

• ping: Health check
• count_users_in_platform: Direct database query
• get_current_user: Authentication helper
• get_user_platforms: Authentication helper

Troubleshooting

Authentication Issues

"Unauthorized" errors: Check your API key is correct and hasn't expired.

"Could not authenticate mentor": Verify the X-Mentor-Unique-Id header is set correctly.

Connection issues: Ensure the instance URL is correct and accessible.

Common Parameter Errors

"platform_key is required" (Analytics & Search):

• Most analytics endpoints require the platform_key parameter
• Example: get_content_analytics(metric="courses", platform_key="ibl")
• The platform_key should match your organization/platform identifier

"Invalid parameters" (Search):

• get_mentor_search requires platform_key for authenticated requests
• Use either platform_key or tenant parameter (both serve the same purpose)

"Document pathway is not a valid mentor unique id" (Agent Create):

• When using post_train_document or post_retriever_train, the pathway parameter must be a valid mentor UUID
• Use the mentor's unique ID (not the mentor name or slug)
• Example: pathway="ad2be335-5afa-4a9e-9298-8273b3d94e10"

"We couldn't reach the website" (Agent Create):

• When training documents from URLs, ensure the URL is publicly accessible
• The URL may be blocked, require authentication, or be offline
• Verify the URL works in a browser before using it

Permission Errors

"Requires admin user" (Analytics):

• Some endpoints like get_web_analytics_time_spent_per_user require admin privileges
• Ensure your API key has admin permissions for the platform

Best Practices

1. Always include platform_key for analytics and search operations
2. Use mentor UUIDs (not names) for pathway parameters in document training
3. Test with simple prompts first (e.g., "hello") before complex queries
4. Check URL accessibility before training documents from external sources
5. Use health check tools (ping) to verify server connectivity