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": "[email protected]",
    "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):

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

Troubleshooting

"Permission Denied" Error

Problem: Receiving 403 Forbidden when accessing admin endpoints

Solutions:

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

Filter Not Applied

Problem: Content filter isn't blocking expected keywords

Solutions:

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

Tool Not Appearing

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

Solutions:

Verify MCP Tools service is running
Check service has registered the tool
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.

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

MCP Admin Interface Guide

On this page