MCP Server Usage

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:

OAuth redirect to /authorize endpoint
Browser opens with VOSS login page
User enters credentials
OAuth token exchanged and cached
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-host>/<instance-key>/mcp",
      "enabled": true
    }
  }
}

Cursor / VS Code#

File: .cursor/mcpServers.json in project root, or settings UI

{
  "mcp": {
    "voss-automate": {
      "type": "remote",
      "url": "https://<mcp-host>/<instance-key>/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-host>/<instance-key>/mcp`
Auth	OAuth (browser-based)

Claude Code (CLI)#

File: ~/.claude/settings.json

{
  "mcp": {
    "voss-automate": {
      "type": "remote",
      "url": "https://<mcp-host>/<instance-key>/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://<internal-host>/<instance-key>/mcp"
      }
    }
  }
}

Full example:

{
  "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://<mcp-host>/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

MCP Server Usage

On this page

MCP Server Usage#

Overview#

Available MCP Tools#

Authentication (OAuth-only)#

Usage Examples#

Login Flow#

User Onboarding#

Transaction Monitoring#

Ask Wingman AI#

Long-Running Wingman Queries (ChatGPT Mode)#

Wingman Conversation History#

Get User Info#

Find Existing User#

List Hierarchies#

Interface-Specific Configuration#

Claude Desktop / Claude Code#

Cursor / VS Code#

ChatGPT (OpenAI)#

Claude Code (CLI)#

HTTP Bridge (For Internal/VPN Endpoints)#

Health Check Verification#

Troubleshooting Config Issues#