@faqai/mcp-server

Official Model Context Protocol server for FAQai.app — turn any document into a production-ready RAG dataset directly from Claude Desktop, Cursor, or any MCP host.

Requirements

• Node.js 18+
• A FAQai API key (faq_...) — create one at faqai.app/settings/api-keys. API access requires a paid plan (Basic or higher).

Setup

Claude Desktop / Cursor

Add to your MCP configuration (claude_desktop_config.json or ~/.cursor/mcp.json):

{
  "mcpServers": {
    "faqai": {
      "command": "npx",
      "args": ["-y", "@faqai/mcp-server"],
      "env": {
        "FAQAI_API_KEY": "faq_your_key_here"
      }
    }
  }
}

Environment variables

| Variable | Required | Default | Description | |---|---|---|---| | FAQAI_API_KEY | Yes | — | Your FAQai API key. Never hardcode it in shared files. | | FAQAI_BASE_URL | No | https://faqai.app | Override for testing against a different environment. |

Tools

| Tool | Type | Description | |---|---|---| | list_documents | Read-only | List your documents with status, page count, and dataset counts | | get_document | Read-only | Full details for one document | | get_processing_status | Read-only | Poll a document's processing state | | list_export_formats | Read-only | The 16 supported dataset export formats | | get_usage_stats | Read-only | Current plan, page/API-call quota, and limits | | list_datasets | Read-only | Datasets generated for a document, with IDs for export | | export_dataset | Read-only | Export a dataset in any of 16 formats, inline or to a local file | | search_datasets | Read-only | Full-text search across all generated Q&A items | | get_dataset_coverage | Read-only | Chunk-level coverage report for a dataset | | get_rag_config | Read-only | Tuned system prompt, embedding config, and code snippets | | upload_document | Write | Upload a local PDF/DOCX/TXT/MD (presigned flow, quota pre-check); supports optional generation_context (audience steering) and chunking (profile presets or custom sizes) | | ingest_url | Write | Ingest a public web page or crawl a same-domain site (sitemap/BFS, robots.txt-aware, per-plan page caps) into a new document; supports the same optional generation_context and chunking fields | | process_document | Write | Start dataset generation — consumes page quota; supports the same optional generation_context and chunking fields | | cancel_processing | Write | Cancel an in-flight processing run and release reserved pages | | delete_document | Destructive | Permanently delete a document; requires explicit confirm: true | | list_webhooks | Read-only | List webhook subscriptions (Pro plan) | | create_webhook | Write | Subscribe an HTTPS endpoint to FAQai events (Pro plan) | | delete_webhook | Destructive | Remove a webhook subscription (Pro plan) |

Resources & Prompts

Besides tools, the server exposes MCP resources — faqai://documents (recent documents) and faqai://usage (plan quota) — that hosts can attach to a conversation as context, and two prompts (slash commands in most hosts):

• generate-rag-dataset — upload a local file, wait for processing, and report the generated datasets with coverage.
• export-to-vector-db — export a document's dataset in the right format for Pinecone, Qdrant, pgvector, Chroma, Weaviate, Milvus, LanceDB, or Upstash.

Typical agent workflow

1. upload_document with a local file path, or ingest_url with a web page / site URL (starts processing by default)
2. get_processing_status — poll every 10–15 s until completed
3. list_datasets — get the generated dataset IDs
4. export_dataset with save_path — write the dataset to disk in the format your stack needs

Security

• The server communicates exclusively with the public FAQai REST API over HTTPS using your API key. It has no other credentials and no database access. All plan limits, rate limits, quotas, and row-level security apply exactly as they do for direct API usage.
• Your API key is read from the environment and is never logged or echoed.
• Use a scoped key. If you only need the agent to read documents and export datasets, create a key with the read scope only — write tools (upload_document, ingest_url, process_document, cancel_processing, delete_document) will then be rejected by the API with a 403 even if the agent calls them.
• delete_document is guarded twice: the tool refuses to run without confirm: true, and it is annotated destructiveHint so well-behaved MCP hosts ask the user before invoking it.
• Every tool invocation is logged to stderr with a timestamp, outcome, and duration, giving you a local audit trail of what the agent did with your account. Most MCP hosts surface these logs (Cursor: Output panel → MCP; Claude Desktop: ~/Library/Logs/Claude/mcp*.log).
• Quota protection: upload_document checks your remaining page quota before uploading and refuses when it is exhausted, and every response carries a plan-usage note so the agent can warn you before starting expensive jobs.

Troubleshooting

| Symptom | Cause / fix | |---|---| | FAQAI_API_KEY environment variable is required | The key is missing from the MCP config env block. | | Authentication failed (401) | The key is invalid or revoked — create a new one at faqai.app/settings/api-keys. | | Access denied (403) on every tool | API access requires a paid plan (Basic or higher). | | 403 only on write tools | Your key is scoped read — intended behavior; create a write scoped key if you want uploads. | | Rate limited (429) | Wait the indicated seconds. Plans allow 10–30 requests/minute. | | page_limit_exceeded | Monthly page quota exhausted — upgrade or buy an overage pack. | | Export "too large to return inline" | Call export_dataset again with save_path set to an absolute file path. | | Server exits immediately | Run node dist/index.js manually; startup errors are printed to stderr. |

When reporting an issue, include the server version — it is printed on startup ([faqai-mcp] vX.Y.Z ready) and embedded in unexpected-error messages.

Development

npm install
npm run build
npm test

Live smoke test against the real API (read-only by default):

FAQAI_PRO_API_KEY=faq_... node tests/live-smoke.mjs
# full write-path E2E (uploads + processes + deletes a tiny test doc, ~1 page of quota):
FAQAI_PRO_API_KEY=faq_... LIVE_E2E=1 node tests/live-smoke.mjs
# target a dev server:
FAQAI_PRO_API_KEY=faq_... FAQAI_BASE_URL=http://localhost:3000 LIVE_E2E=1 node tests/live-smoke.mjs

License

MIT