Webex API Docs MCP Server (webex-api-docs-mcp)

An MCP (Model Context Protocol) server providing fast, local full-text search and complete OpenAPI JSON schemas for all Webex Developer APIs & RoomOS xAPI.

💡 What Problem Does This Solve? (Why Use This MCP Server?)

🔴 The Problem: Hallucinations & Massive Token Cost

When AI Agents or developers work with Webex APIs, they face three major bottlenecks:

• LLM Hallucinations: Large language models frequently guess incorrect HTTP methods, outdated REST paths, or invent required OAuth scopes (spark-admin:...) that lead to 401 Unauthorized or 404 Not Found errors.

• Context Window Exhaustion: The official Webex OpenAPI and RoomOS xAPI specifications span over 4,500 endpoints across Admin, Calling, Meetings, Messaging, and RoomOS—equaling more than 15 MB of raw documentation. Loading this into an LLM context window is slow, expensive, and impractical.

• Slow Web Scraping: Relying on live web searches to fetch developer documentation during an agentic coding workflow causes latency and fragile HTML parsing.

🟢 The Solution: Zero-Token Local Search & Exact Schemas

This MCP server acts as an authoritative, local technical reference for your AI Assistant. Instead of guessing or browsing the web, the AI can query the local SQLite FTS5 database in <5 milliseconds, discover the exact endpoint, and retrieve its complete, verified OpenAPI JSON schema on demand.

🎯 Real-World Examples & Use Cases

Here are examples of questions and tasks your AI Agent can solve instantly using this MCP server:

1. 🔒 Security & Admin Audit Logging

   • User Prompt: "I need to write a script that logs who deleted a user account in Webex Control Hub. What endpoint should I call and what permissions do I need?"

   • MCP Action: Uses search_webex_api_docs("audit events") -> Returns GET /adminAudit/events -> Uses get_webex_endpoint_schema to inspect actorEmail, eventDescription, and the required audit:events_read scope.

2. 📞 Telephony & AI Receptionist Automation

   • User Prompt: "How do I programmatically create an AI Receptionist Knowledge Base in Webex Calling?"

   • MCP Action: Uses search_webex_api_docs("knowledge base") -> Locates POST /telephony/config/knowledgeBases -> Retrieves the exact JSON Request Body schema showing mandatory fields (name, description).

3. 📝 Meeting Summaries & Transcripts

   • User Prompt: "What is the REST API path to download post-meeting transcripts and AI summaries?"

   • MCP Action: Searches meetings domain for "transcripts" -> Finds GET /meetings/{meetingId}/transcripts and GET /meetings/{meetingId}/summaries along with query parameters.

4. 🤖 Messaging Bots & Webhooks

   • User Prompt: "I want my bot to receive real-time notifications when a message is posted in a Webex room."

   • MCP Action: Locates POST /webhooks in the messaging domain and returns the required payload structure for messages/created events.

5. 📺 RoomOS xAPI Device Automation & AirPlay

   • User Prompt: "How do I control AirPlay or adjust volume on a Cisco Room Bar using xAPI?"

   • MCP Action: Searches roomos domain -> Finds xCommand AirPlay KeyEvent Back and xCommand Audio Volume Set -> Retrieves syntax for Webex Cloud REST API (POST /v1/xapi/command/...), Node.js jsxapi, and on-device CLI/Macros.

Related MCP server: punt-quarry

🌟 Why This Architecture? (Dual-Layer Documentation)

This repository implements a scalable, reproducible, and Git-versioned documentation pipeline designed specifically for AI Agents and developers:

1. Layer 1: Markdown Artifacts in Git (docs/<domain>.md)

   • Clean, structured Markdown documentation for Webex Admin, Webex Cloud Calling, Webex Meetings, Webex Messaging, and Webex RoomOS xAPI is generated automatically and stored in /docs/.

   • Every time Webex updates an API, running the ETL pipeline produces a standard Git diff so you can track API changes over time.

2. Layer 2: SQLAlchemy + SQLite FTS5 Index (data/webex_docs.db)

   • An optimized SQLite relational database managed via SQLAlchemy 2.0 ORM combined with SQLite FTS5 (Full-Text Search).

   • Provides sub-millisecond keyword and semantic search across 4,539 endpoints without loading multi-megabyte files into memory or context.

📦 What's Included?

The server indexes 4,539 official Webex endpoints across 5 major service domains:

🛠️ Installation & Setup

1. Clone the repository and install dependencies:

   git clone https://github.com/santime27/mcp-server-webex-docs.git
   cd mcp-server-webex-docs
   pip install -r requirements.txt

2. Run the automated ETL pipeline (Optional - Rebuild docs and DB index):

   python3 -m src.pipeline.build_all

   This extracts the OpenAPI schemas, generates the 4 Markdown files in docs/, and builds the SQLite FTS5 database at data/webex_docs.db.

3. Start the MCP Server:

   python3 -m src.server

🔌 How to Connect This MCP Server (Configuration)

Thanks to automatic path resolving in src/server.py, connecting this server to any MCP client is ultra-simple—no PYTHONPATH, cwd, or -m flags required!

1. Gemini CLI / Google Antigravity / Gemini Code Assist

Add this to your Gemini MCP settings file (e.g., ~/.gemini/settings.json or your project's MCP configuration):

{
  "mcpServers": {
    "webex-api-docs": {
      "command": "python3",
      "args": [
        "/path/to/mcp-server-webex-docs/src/server.py"
      ]
    }
  }
}

2. Claude Desktop / Cursor / Generic MCP Client (claude_desktop_config.json)

{
  "mcpServers": {
    "webex-api-docs": {
      "command": "python3",
      "args": [
        "/path/to/mcp-server-webex-docs/src/server.py"
      ]
    }
  }
}

Note: Replace /path/to/mcp-server-webex-docs with the absolute path where you cloned this repository on your machine.

🤖 MCP Tools Exposed for AI Agents

When connected to an MCP client (such as Claude Desktop, Antigravity, or custom agents), this server exposes the following tools:

• search_webex_api_docs(query, domain=None, category=None, limit=15)

  • Sub-millisecond FTS5 search across all 1,456 endpoints. Returns endpoint titles, HTTP method/path, summary, and exact line numbers in the documentation file.

• get_webex_endpoint_schema(domain, section_number)

  • Reads the exact line range from docs/<domain>.md and returns the complete OpenAPI JSON schema, parameter table, required scopes, and HTTP response codes for a specific endpoint.

• list_webex_domains()

  • Lists the 4 available Webex domains and their endpoint counts.

• list_webex_categories(domain)

  • Lists all categories available within a specific domain.

📁 Repository Structure

mcp-server-webex-docs/
├── agent-skills/              # AI Agent Skills (instructions & templates)
│   └── webex-api-assistant/   # Methodology for discovering, inspecting, and exploring APIs
│       ├── SKILL.md
│       ├── examples/
│       │   └── explorer_template.py
│       └── references/
│           └── webex_api_cheatsheet.md
├── docs/                      # Git-versioned Markdown documentation
│   ├── admin.md
│   ├── calling.md
│   ├── meetings.md
│   ├── messaging.md
│   └── roomos.md              # Webex RoomOS xAPI Commands, Configurations, Statuses & Events
├── data/
│   ├── roomos_schema.json     # Cached official RoomOS xAPI schema (3,083 objects)
│   └── webex_docs.db          # SQLite FTS5 database indexed via SQLAlchemy
├── src/
│   ├── models/                # SQLAlchemy ORM models (Domain, Category, Endpoint)
│   │   ├── __init__.py
│   │   └── db.py
│   ├── pipeline/              # ETL pipeline for automated updates
│   │   ├── __init__.py
│   │   ├── build_all.py       # Main orchestrator CLI
│   │   ├── db_indexer.py      # SQLite FTS5 indexer
│   │   ├── fetcher.py         # Developer portal state extractor
│   │   ├── markdown_builder.py# Markdown generator (Admin, Calling, Meetings, Messaging)
│   │   └── roomos_builder.py  # RoomOS xAPI schema & Markdown generator
│   ├── __init__.py
│   └── server.py              # MCP FastMCP server implementation
├── requirements.txt

🧠 AI Agent Skill (agent-skills/webex-api-assistant)

This repository includes an official Agent Skill in agent-skills/webex-api-assistant/SKILL.md designed to teach any AI Assistant (such as Antigravity, Claude, or Cursor) how to act as a Senior Webex Developer Companion.

The skill instructs the model on:

1. The 2-Step MCP Workflow: Always discovering APIs via search_webex_api_docs first, then inspecting full OpenAPI schemas and OAuth scopes via get_webex_endpoint_schema.

2. Interactive Sandbox Exploration: Generating and executing clean Python exploration scripts in a sandbox/temporary environment to test live APIs.

3. Security Best Practices: Reading WEBEX_ACCESS_TOKEN from environment variables without ever hardcoding tokens.

👨‍💻 Authors & Credits

Built with ❤️ by Santiago Meneses Garcia, Software Engineer, in pair-programming collaboration with Antigravity (Google DeepMind Agentic AI Assistant).

📄 License

This project is licensed under the permissive MIT License — feel free to use, copy, modify, distribute, and build upon this software for both personal and commercial projects without restrictions.