MCP Server Usage ===================== Overview -------- VOSS hosts a Model Context Protocol (MCP) server that provides AI assistants (Claude, ChatGPT, Cursor, and so on) with secure access to VOSS operations through the Model Context Protocol. This allows users to interact with their VOSS platform from within the assistant. A number of tools are available for queries related to user management, onboarding, transaction monitoring, and Wingman AI assistance. This section covers the available tools, example usage, and configuration guidance for AI assistants. Available MCP Tools ------------------- +--------------------------------+------------------------------------------------+ | Tool | Description | +================================+================================================+ | ``login`` | Get a clickable link to the authentication | | | page for secure credential entry | +--------------------------------+------------------------------------------------+ | ``get_my_info`` | Retrieves user session and account information | | | from VOSS | +--------------------------------+------------------------------------------------+ | ``onboard_user`` | Complete user onboarding workflow with | | | hierarchy, profile, and line selection | +--------------------------------+------------------------------------------------+ | ``list_all_hierarchies`` | List all available hierarchies (optionally | | | filtered by node type) | +--------------------------------+------------------------------------------------+ | ``get_subscriber_profiles`` | Get available subscriber profiles for a | | | hierarchy | +--------------------------------+------------------------------------------------+ | ``get_inventory_filters`` | Get available inventory filters for line | | | selection | +--------------------------------+------------------------------------------------+ | ``find_user`` | Search for an existing user by username | +--------------------------------+------------------------------------------------+ | ``check_transaction_status`` | Monitor transaction status (Queued, | | | Processing, Success, Fail) | +--------------------------------+------------------------------------------------+ | ``ask_wingman`` | Ask the Wingman AI agent questions about data, | | | troubleshooting, actions | +--------------------------------+------------------------------------------------+ | ``check_wingman_run_status`` | Poll status/progress for long-running Wingman | | | runs | +--------------------------------+------------------------------------------------+ | ``cancel_wingman_run`` | Cancel a long-running Wingman run | +--------------------------------+------------------------------------------------+ | ``wingman_list_conversations`` | List past Wingman conversations | +--------------------------------+------------------------------------------------+ | ``wingman_get_history`` | Retrieve full message history for a | | | conversation | +--------------------------------+------------------------------------------------+ Authentication (OAuth-only) --------------------------- The MCP server uses **OAuth 2.1** for authentication. **OAuth Endpoints:** +-----------------------------------------------+----------+-----------------------------+ | Endpoint | Method | Description | +===============================================+==========+=============================+ | ``/.well-known/oauth-authorization-server`` | GET | OAuth AS metadata | +-----------------------------------------------+----------+-----------------------------+ | ``/.well-known/oauth-protected-resource/mcp`` | GET | Protected resource metadata | +-----------------------------------------------+----------+-----------------------------+ | ``/authorize`` | GET/POST | Authorization endpoint | | | | (browser login) | +-----------------------------------------------+----------+-----------------------------+ | ``/token`` | POST | Token exchange | | | | (``authorization_code`` + | | | | PKCE) | +-----------------------------------------------+----------+-----------------------------+ Usage Examples -------------- The examples below illustrate the use of the VOSS MCP tools. Login Flow ............. The login is handled via OAuth browser-based authentication. When you first connect, you are redirected to authorize: :: # Cursor/VS Code MCP Config { "mcpServers": { "voss-mcp": { "url": "https://mcp.customerA.voss-solutions.com/mcp" } } } First connection triggers: 1. OAuth redirect to /authorize endpoint 2. Browser opens with VOSS login page 3. User enters credentials 4. OAuth token exchanged and cached 5. MCP tools become available User Onboarding .................. :: User: "onboard user jdoe" MCP Tool Call (internal):: { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "onboard_user", "arguments": { "username": "jdoe", "first_name": "John", "last_name": "Doe", "email": "jdoe@company.com" } } } Response:: Onboarding request initiated for user jdoe. Transaction ID: 658189870509a259c4059048 Use check_transaction_status(658189870509a259c4059048) to monitor. Transaction Monitoring .......................... :: User: "Check status of transaction 658189870509a259c4059048" MCP Tool Call:: { "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "check_transaction_status", "arguments": { "transaction_id": "658189870509a259c4059048" } } } Expected statuses: ``Queued`` -> ``Processing`` -> ``Success`` or ``Fail`` Ask Wingman AI ................. :: User: "Ask Wingman how many phones we have in our environment" MCP Tool Call:: { "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "ask_wingman", "arguments": { "question": "How many phones do we have?", "hierarchy_id": "site-123" } } } Response (streaming via SSE):: ## Phone Count | Metric | Count | |--------------|-------| | Total Phones | 253 | --- **Resource**: Cisco UCM Phone **Intent**: get-resource-widget **Conversation ID**: c63cadfd-eb7b-4ab5-b020-75d3b1dd97fc Long-Running Wingman Queries (ChatGPT Mode) .............................................. For complex queries that take time, Wingman returns a ``run_id`` for async polling: :: User: "Ask Wingman to investigate failed calls in the last 7 days" Response: :: Wingman run started with run_id: f47ac10b-58cc-4372-a567-3821b4d95e64 Current status: Running Use check_wingman_run_status(f47ac10b-58cc-4372-a567-3821b4d95e64) to poll for completion. Poll for completion: :: User: "Check Wingman run status for f47ac10b-58cc-4372-a567-3821b4d95e64 and wait" Wingman Conversation History ................................. :: User: "List my Wingman conversations" MCP Tool Call:: { "jsonrpc": "2.0", "id": 4, "method": "tools/call", "params": { "name": "wingman_list_conversations", "arguments": { "hierarchy_id": "site-123" } } } Response: :: ## Wingman Conversations | Conversation | Title | Last Updated | Messages | |--------------------------------------|---------------------|--------------|----------| | c63cadfd-eb7b-4ab5-b020-75d3b1dd97fc | Phone Investigation | 2025-04-20 | 12 | | a92bf1c3-d4e5-6f78-9012-c3d4e5f6789a | SSO Config Help | 2025-04-18 | 5 | Get history for conversation c63cadfd-eb7b-4ab5-b020-75d3b1dd97fc Get User Info ................. :: User: "What's my account information?" MCP Tool Call:: { "jsonrpc": "2.0", "id": 5, "method": "tools/call", "params": { "name": "get_my_info", "arguments": {} } } Response: :: ## Account Information | Field | Value | |--------------|------------------| | Username | jdoe@company.com | | Hierarchy | Site: NYC-Office | | Hierarchy ID | site-123 | | User Type | Site Admin | Find Existing User ...................... :: User: "Find user 'asmith'" MCP Tool Call:: { "jsonrpc": "2.0", "id": 6, "method": "tools/call", "params": { "name": "find_user", "arguments": { "username": "asmith" } } } Response: :: ## User Search Results | Username | First Name | Last Name | Email | Status | |----------|------------|-----------|--------------------|--------| | asmith | Alice | Smith | asmith@company.com | Active | Hierarchy: Customer-A List Hierarchies ................... :: User: "Show me all available hierarchies" MCP Tool Call:: { "jsonrpc": "2.0", "id": 7, "method": "tools/call", "params": { "name": "list_all_hierarchies", "arguments": { "node_type": "Site" } } } Response: :: ## Available Hierarchies | Hierarchy ID | Name | Type | |--------------|------------|----------| | site-123 | NYC-Office | Site | | site-456 | LA-Office | Site | | cust-A | Acme Corp | Customer | Interface-Specific Configuration -------------------------------- The examples below show how to configure the MCP server in your interface. Claude Desktop / Claude Code ............................. For example: | **File:** ``~/Library/Application Settings/Claude Desktop/claude_desktop_config.json`` (macOS) | **File:** ``%APPDATA%\Claude Desktop\claude_desktop_config.json`` (Windows) :: { "mcp": { "voss-automate": { "type": "remote", "url": "https:////mcp", "enabled": true } } } Cursor / VS Code ................ **File:** ``.cursor/mcpServers.json`` in project root, or settings UI :: { "mcp": { "voss-automate": { "type": "remote", "url": "https:////mcp", "enabled": true } } } **For VS Code Extensions - settings.json:** :: { "mcp": { "voss-automate": { "type": "remote", "url": "https://mcp.customerA.voss-solutions.com/mcp" } } } ChatGPT (OpenAI) ................ Via **Settings > Explore > Connect an app** in the ChatGPT web interface: +----------+------------------------------------------+ | Setting | Value | +==========+==========================================+ | App URL | ``https:////mcp``| +----------+------------------------------------------+ | Auth | OAuth (browser-based) | +----------+------------------------------------------+ Claude Code (CLI) ................. **File:** ``~/.claude/settings.json`` :: { "mcp": { "voss-automate": { "type": "remote", "url": "https:////mcp", "enabled": true } } } HTTP Bridge (For Internal/VPN Endpoints) ......................................... When the MCP server is not directly accessible (internal HTTP behind VPN), use the stdio bridge: :: { "mcp": { "voss-automate": { "command": "python3", "args": [ "/path/to/connectors/mcp-http-bridge.py" ], "env": { "MCP_HTTP_ENDPOINT": "http:////mcp" } } } } **Full example:** .. code:: json { "mcp": { "voss-internal": { "command": "python3", "args": [ "/opt/voss-mcp/connectors/mcp-http-bridge.py" ], "env": { "MCP_HTTP_ENDPOINT": "http://mcp.internal.company.com/mcp", "MCP_BRIDGE_ALLOW_INSECURE_HTTP": "true", "MCP_BRIDGE_OAUTH_CLIENT_ID": "customer-a", "MCP_BRIDGE_TIMEOUT": "120" } } } } Health Check Verification ------------------------- After configuration, verify connectivity:: # Check health endpoint curl https:///health # Expected response: { "status": "healthy", "automate": "connected", "version": "1.0.0", "uptime_seconds": 3600 } Troubleshooting Config Issues ----------------------------- +---------------------+------------------------------------------+ | Symptom | Solution | +=====================+==========================================+ | Connection refused | Verify server running, check port | | | 8000 | +---------------------+------------------------------------------+ | 401 Unauthorized | Re-run OAuth flow in browser | +---------------------+------------------------------------------+ | Invalid certificate | Use | | | ``MCP_BRIDGE_ALLOW_INSECURE_HTTP: true`` | | | (VPN only) | +---------------------+------------------------------------------+ | Path not found | Verify instance key matches | | | configured route | +---------------------+------------------------------------------+ | Timeout | Increase timeout for long-running | | | queries | +---------------------+------------------------------------------+