Administrator Guides

Comprehensive guides for platform administrators configuring Diosc assistants.

Overview

These guides cover enterprise-critical features for configuring and managing DioscHub assistants. Each guide provides both REST API examples and natural language examples using the MCP Admin Server.

Available Guides

Guide	Description	Key Features
Roles & Permissions	Configure role-based access control and tool filtering	Tool access lists, prompt instructions, role resolution
Approval Policies	Set up human-in-the-loop approval workflows	Tool approvals, timeouts, audit logs
Sitemap & Navigation	Configure intelligent navigation for your application	Dynamic URLs, placeholder resolvers, navigation discovery

Prerequisites

To use these guides, you need:

1. Admin Access

Either:

• Admin API Access: Token with admin permissions (X-Admin-Token header)
• MCP Admin Server: Claude Desktop configured with the MCP Admin Server

2. Assistant ID

Your assistant's unique identifier (format: ast_abc123...)

Get it via:

GET /admin/assistants
X-Admin-Token: your-admin-token

Or ask Claude Desktop (with MCP Admin Server):

List all assistants

3. Understanding of Your Application

• What APIs/tools you're connecting (for role filtering)
• What operations are risky (for approval policies)
• Your app's URL structure (for sitemap)

Admin API vs MCP Admin Server

You have two ways to configure Diosc:

Option 1: Admin API (REST)

Best for:

• Programmatic setup
• CI/CD pipelines
• Scripts and automation
• Bulk operations

Example:

POST /admin/assistants/{assistantId}/roles
Content-Type: application/json
X-Admin-Token: your-admin-token

{
  "roleName": "viewer",
  "allowAllTools": false,
  "allowedToolNames": ["get_user", "get_order", "search_orders", "list_reports"]
}

Documentation:

• Admin API Reference (coming soon)
• Swagger/OpenAPI docs at: {your-hub}/api/admin/docs

Option 2: MCP Admin Server (Natural Language)

Best for:

• Interactive setup
• Exploration and testing
• Quick changes
• Learning the system

Example:

Create a viewer role that can only use read operations like get, search, and list

Setup:

• MCP Admin Server Setup Guide

Both approaches provide identical functionality - choose based on your workflow.

Getting Started

1. Set Up Roles (Optional but Recommended)

Start with role-based access control to filter which tools each user type can access:

[Your Setup] → [Roles Guide] → Roles configured

When to set up roles:

• You have multiple user types (admin, user, viewer)
• Compliance requires access segregation
• You want least-privilege access

Skip if:

• All users have identical permissions
• BYOA authentication handles all access control

Read the Roles Guide →

2. Add Approval Policies

Require human confirmation for risky operations:

[Roles Set Up] → [Approval Policies Guide] → Approvals configured

When to add approval policies:

• Destructive operations (deletes, closes)
• Financial transactions
• Admin functions
• Compliance requirements

Skip if:

• All operations are safe to automate
• Backend APIs provide sufficient safeguards

Read the Approval Policies Guide →

3. Configure Navigation (If Needed)

Let AI navigate your app on behalf of users:

[Approvals Set Up] → [Sitemap Guide] → Navigation configured

When to configure navigation:

• Users ask AI to "open" or "go to" pages
• You have dynamic URLs (product IDs, user IDs, etc.)
• You want AI to discover valid paths

Skip if:

• Navigation is handled client-side only
• No need for AI to navigate

Read the Sitemap Guide →

Common Workflows

Workflow 1: Secure Enterprise Setup

For compliance-heavy environments:

1. Roles → Strict tool filtering (viewer, user, admin)
2. Approval Policies → Require approval for destructive ops
3. Audit Logs → Enable logging for all admin actions
4. Role Resolver → Configure external role resolution (LDAP, database)

Time: ~30 minutes

Workflow 2: SaaS Application

For multi-tenant SaaS:

1. Roles → Tenant-scoped roles (tenant_admin, tenant_user)
2. Navigation → Dynamic paths with tenant IDs
3. Approval Policies → Require approval for cross-tenant operations

Time: ~45 minutes

Workflow 3: Internal Tool

For internal dashboards/tools:

1. Navigation → Simple sitemap (no complex resolvers)
2. Roles → Basic (admin, user)
3. Skip approval policies (unless needed)

Time: ~15 minutes

Quick Reference

Roles & Permissions

# Create role
POST /admin/assistants/{id}/roles
{
  "roleName": "viewer",
  "allowAllTools": false,
  "allowedToolNames": ["get_user", "get_order", "search_orders", "list_reports"]
}

# List roles
GET /admin/assistants/{id}/roles

Approval Policies

# Create policy
POST /admin/assistants/{id}/approval-policies
{
  "toolPattern": "delete_*",
  "timeoutSeconds": 120
}

# Query logs
POST /admin/assistants/{id}/approval-logs/query
{
  "decision": "rejected",
  "limit": 100
}

Sitemap & Navigation

# Add static page
POST /admin/assistants/{id}/sitemap
{
  "pathPattern": "/dashboard",
  "displayName": "Main Dashboard"
}

# Add dynamic page
POST /admin/assistants/{id}/sitemap
{
  "pathPattern": "/products/{productId}/details",
  "displayName": "Product Details",
  "placeholders": [...]
}

Best Practices Summary

Security

1. Start restrictive → Expand as needed (roles, approvals)
2. Layer defenses → Roles + BYOA + Approvals + Backend Auth
3. Audit regularly → Review logs and configurations
4. Version control → Export and store configurations

Usability

1. Descriptive names → Use clear role names, display names
2. Helpful descriptions → Add context to approval dialogs
3. Reasonable timeouts → Don't rush users, don't stall AI
4. Test end-to-end → Verify behavior after changes

Maintenance

1. Document decisions → Why you chose specific patterns
2. Monitor metrics → Approval rates, rejection patterns
3. Iterate based on feedback → Adjust based on user experience
4. Keep it simple → Don't over-configure

Troubleshooting

General Issues

Issue	Check
Configuration not applying	Verify isActive: true, check assistant ID
API returns 401/403	Check admin token, verify permissions
MCP Admin Server not working	Verify Claude Desktop setup, check logs
Changes not reflected	Restart session, check caching

Specific Guides

• Roles: See Roles Troubleshooting
• Approvals: See Approval Troubleshooting
• Navigation: See Sitemap Troubleshooting

Related Documentation

For Administrators

• Roles & Permissions - This guide
• Approval Policies - This guide
• Sitemap & Navigation - This guide

For Developers

• Client SDK Reference - Frontend integration
• Authentication Guide - BYOA setup
• MCP Integration - Connect backend APIs

Architecture

• BYOA Philosophy - Authentication approach
• Dual-Agent Model - Server/client architecture
• Architecture Overview - System design

Support

Need help?

1. Check the specific guide's troubleshooting section
2. Review API documentation: {your-hub}/api/admin/docs
3. Check MCP Admin Server logs: See Claude Desktop setup
4. Open an issue on GitHub

---

Start with: Roles & Permissions →