mcp-admin-interface.md

MCP Admin Interface Guide

Complete guide for administrators managing MCP (Model Context Protocol) tools without code changes.

Overview

The MCP Admin Interface allows administrators to dynamically configure MCP tools through the LLM API, without requiring service restarts or code deployments. This guide covers:

• Viewing and listing MCP tools
• Editing tool configurations
• Enabling/disabling tools
• Setting content filtering rules
• Managing tool access and permissions

Architecture

Platform Web (Admin UI)
    ↓
LLM API
    ↓
Database (admin_mcp_tools table)
    ↓
MCP Tools Service (Tool Registration)

Quick Start

List Available MCP Tools

GET /v1/admin/mcp/tools

View all MCP tools available in your system.

curl -H "Authorization: Bearer <admin-token>" \
  http://localhost:8000/v1/admin/mcp/tools

Response:

{
  "data": [
    {
      "id": "tool_1",
      "tool_key": "google_search",
      "name": "Google Search",
      "description": "Search the web using Google",
      "category": "search",
      "enabled": true,
      "disallowed_keywords": []
    },
    {
      "id": "tool_2",
      "tool_key": "python_exec",
      "name": "Python Executor",
      "description": "Execute Python code securely",
      "category": "code",
      "enabled": true,
      "disallowed_keywords": ["delete", "drop", "rm"]
    }
  ]
}

Enable/Disable a Tool

PATCH /v1/admin/mcp/tools/{tool_id}

Enable or disable a tool for all users.

curl -X PATCH http://localhost:8000/v1/admin/mcp/tools/tool_1 \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": false
  }'

Managing MCP Tools

Get Tool Details

GET /v1/admin/mcp/tools/{tool_id}

View complete configuration for a specific tool.

curl -H "Authorization: Bearer <admin-token>" \
  http://localhost:8000/v1/admin/mcp/tools/tool_2

Response:

{
  "id": "tool_2",
  "tool_key": "python_exec",
  "name": "Python Executor",
  "description": "Execute Python code",
  "category": "code",
  "enabled": true,
  "disallowed_keywords": ["delete", "drop", "format", "rm.*recursive"],
  "created_at": "2025-12-20T10:00:00Z",
  "updated_at": "2025-12-23T11:00:00Z"
}

Update Tool Configuration

PATCH /v1/admin/mcp/tools/{tool_id}

Modify tool name, description, or enable/disable status.

curl -X PATCH http://localhost:8000/v1/admin/mcp/tools/tool_2 \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Safe Python Executor",
    "description": "Execute sandboxed Python code",
    "enabled": true
  }'

Set Content Filtering Rules

PUT /v1/admin/mcp/tools/{tool_id}/filters

Configure regex patterns to block certain keywords/patterns in tool arguments.

curl -X PUT http://localhost:8000/v1/admin/mcp/tools/tool_2/filters \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "disallowed_keywords": [
      "^delete\\s+",
      "^drop\\s+",
      "^rm\\s+-rf",
      "os\\.remove",
      "__import__\\(.*os.*\\)"
    ]
  }'

Content Filtering

Filter Syntax

Disallowed keywords use regex patterns for flexible matching:

Pattern	Matches	Use Case
^delete\\s+	"delete" at start of string	Block SQL DELETE commands
drop	"drop" anywhere (case-insensitive)	Block DROP statements
os\\.remove	"os.remove" in Python code	Block file deletion
__import__	Python import statements	Restrict imports
eval\\(	"eval(" function calls	Block dangerous eval
exec\\(	"exec(" function calls	Block exec calls

Common Filter Sets

Python Code Execution - Safe Mode

Block potentially dangerous operations:

{
  "disallowed_keywords": [
    "^import os",
    "^import subprocess",
    "^import socket",
    "^import requests",
    "os\\.system",
    "os\\.remove",
    "subprocess\\.call",
    "subprocess\\.run",
    "open\\(",
    "__import__"
  ]
}

Web Search - Content Filter

Block adult/NSFW searches:

{
  "disallowed_keywords": [
    "adult",
    "nsfw",
    "porn",
    "xxx",
    "sex.*site",
    "18\\+.*content"
  ]
}

General Safety Rules

{
  "disallowed_keywords": [
    "delete",
    "drop",
    "truncate",
    "destroy",
    "rm\\s+-rf",
    "format.*drive"
  ]
}

Python Examples

JavaScript Examples

Bulk Tool Status Update

const adminToken = "your_admin_token";
const headers = {
  Authorization: `Bearer ${adminToken}`,
  "Content-Type": "application/json",
};

// Fetch all tools
const listResponse = await fetch("http://localhost:8000/v1/admin/mcp/tools", {
  headers,
});

const tools = await listResponse.json();

// Disable all code execution tools
for (const tool of tools.data) {
  if (tool.category === "code") {
    await fetch(`http://localhost:8000/v1/admin/mcp/tools/${tool.id}`, {
      method: "PATCH",
      headers,
      body: JSON.stringify({ enabled: false }),
    });
    console.log(`Disabled: ${tool.name}`);
  }
}

Access Control

Admin Authentication

The MCP Admin endpoints require admin-level authentication. Ensure your token has appropriate permissions:

# Admin user login
curl -X POST http://localhost:8000/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@example.com",
    "password": "secure_password"
  }'

# Use the returned token for admin operations

Role-Based Access Control (RBAC)

MCP Admin endpoints check for:

• admin role OR
• mcp:admin permission

Configure in your identity provider (Keycloak):

1. Create mcp_admin group in Keycloak
2. Add admin users to the group
3. Map group to mcp:admin scope in JWT token
4. Token will include "scope": "mcp:admin"

Troubleshooting

"Permission Denied" Error

Problem: Receiving 403 Forbidden when accessing admin endpoints

Solutions:

1. Verify token has admin permissions
2. Check token hasn't expired: jwt decode YOUR_TOKEN
3. Ensure user is in admin group/role in Keycloak

Filter Not Applied

Problem: Content filter isn't blocking expected keywords

Solutions:

1. Verify regex syntax is correct
2. Test regex pattern independently
3. Remember regexes are case-sensitive (use (?i) for case-insensitive)
4. Check filter is applied to correct tool

Tool Not Appearing

Problem: Tool exists but doesn't show in admin list

Solutions:

1. Verify MCP Tools service is running
2. Check service has registered the tool
3. Ensure tool registration completed (may need restart)

Best Practices

1. Enable Only Needed Tools

Start with minimal tool set, enable others as needed:

# Disable all tools initially
curl -X PATCH http://localhost:8000/v1/admin/mcp/tools/web_scraper \
  -H "Authorization: Bearer <token>" \
  -d '{"enabled": false}'

2. Test Filters Before Deployment

Test filter patterns against actual use cases:

# Pattern to test: "os\\.system"
# Test inputs:
# - "os.system('ls')"     → BLOCKED ✓
# - "my_os.system_call()" → ALLOWED ✓

3. Audit Tool Usage

Monitor which tools users are accessing:

# Check MCP Tools service logs
docker logs mcp-tools | grep "tool_call"

4. Regular Security Updates

Review tool filters quarterly as new security threats emerge.

Related Documentation

• MCP Tools API Reference - Tool execution API
• Authentication Guide - Admin authentication
• Security Guide - Security best practices
• Deployment Guide - Production configuration

Support

For admin-related issues:

• Check Troubleshooting Guide
• Review MCP Tools Documentation
• Contact your Jan Server administrator

---

Last Updated: December 23, 2025
Compatibility: Jan Server v0.0.14+
Role Required: Admin or mcp:admin permission