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 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

3. 📝 Meeting Summaries & Transcripts

4. 🤖 Messaging Bots & Webhooks

5. 📺 RoomOS xAPI Device Automation & AirPlay

🌟 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/.md`)

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

📦 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/.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.