mcp-server

<p align="center">
  <img src="images/logo.svg" width="72" alt="Mindola logo">
</p>

# Mindola MCP server

Mindola turns a person's own material (writing, notes, documents, links) into a public AI page that answers questions from that material alone, with citations.

That public AI page is called a **lens**: one shareable link, like `https://mindola.ai/me/your-name`, where anyone can ask questions in chat or a live voice call. Every answer is grounded only in the owner's material and shows its sources. If the material does not cover a question, the lens says so honestly instead of guessing, and can hand the question to the real person.

This repository is the public documentation and examples for Mindola's **hosted MCP server**. The server is remote: there is nothing to install or run. You add one URL to your MCP client (Claude, Cursor, VS Code, Codex, ChatGPT), and your AI assistant can create and fill a lens for you in one conversation. The server itself runs inside the Mindola app, which is closed source; this repo holds the docs and example code.

Try a live lens right now, no account needed: [mindola.ai/me/charles-darwin](https://mindola.ai/me/charles-darwin).

## What problem Mindola solves

People publish knowledge that nobody reads. Your blog posts, documentation, course material, and notes sit in archives, and visitors are expected to dig through them. Most will not. They have one question and they want one answer.

A generic AI chatbot is not the fix. It answers from whatever it was trained on, so it confidently makes things up about you, your product, or your work. That is worse than no answer.

Mindola sits in between. It gives your material a front door: a page that answers questions from your knowledge base and nothing else, cites where each answer came from, and admits when it does not know. Visitors get answers instead of archives, and you get to see what they asked.

## Why Mindola instead of building RAG yourself

Building retrieval-augmented generation (RAG) yourself is a real project. You need ingestion for every source type, chunking that respects document structure, embeddings, a vector store, retrieval tuning, grounding logic so the model stays inside your material, a citation UI, refusal behavior for out-of-scope questions, and then hosting, monitoring, and a front end. Add real-time voice and it roughly doubles.

Mindola gives you the finished product behind one link and one API. You provide the material; Mindola handles knowledge retrieval, grounded answers, citations, refusals, voice, the public page, and the inbox for unanswered questions. You can go from nothing to a working grounded AI page in one conversation with your coding assistant.

Building your own is still the right call in some situations. If you need full control over which models run, where your data lives, or how retrieval is ranked, or you want to embed the pipeline deep inside an existing product, roll your own. Mindola is for everyone who wants the outcome without owning the pipeline.

## Core capabilities

- **Grounded answers with citations.** Every answer comes from the owner's material only, and shows its sources. Private material never leaks into citations.
- **Honest refusals.** Out-of-scope questions get a clear "I don't know" instead of a hallucinated answer.
- **Live voice calls.** Visitors can talk to a lens in real time, with barge-in (they can interrupt mid-sentence). Owners can use a cloned voice or a stock voice.
- **Lead capture built in.** Questions the lens cannot answer land in the owner's inbox with the visitor attached, so a lens doubles as light CRM.
- **Optional payments.** Owners can charge visitors through Stripe Connect, using their own Stripe account with per-lens pricing. Off by default.
- **10 app languages.** The app UI supports English, Dutch, German, Spanish, French, Arabic, Japanese, Korean, Turkish, and Chinese.
- **Many uses from one link.** The same lens can be a chatbot for your website, your docs, or your coaching practice, depending on what you feed it.

## Installation

The MCP server is hosted. There is nothing to run locally; you point your client at a URL.

**Claude Code**

```bash
claude mcp add --transport http mindola https://app.mindola.ai/mcp/lens
```

**Cursor** (`~/.cursor/mcp.json` or project `.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "mindola": {
      "url": "https://app.mindola.ai/mcp/lens"
    }
  }
}
```

**Claude Desktop / claude.ai**

Settings -> Connectors -> Add custom connector -> URL `https://app.mindola.ai/mcp/lens`.

For VS Code, Codex CLI, Windsurf, Gemini CLI, ChatGPT, and troubleshooting, see [docs/installation.md](docs/installation.md). Ready-to-copy client configs live in [examples/clients/](examples/clients/).

## Quick start

### With your AI assistant

1. Connect the server using any snippet above.
2. Paste a prompt like this:

```text
Create a Mindola lens for me. I'm a nutrition coach specializing in
plant-based diets for endurance athletes. I've been coaching for 8 years.
Use a warm tone. Ask me anything you need, then show me the profile
before you create it.
```

3. Your assistant drafts a profile (name, bio, expertise, facts, boundaries) and shows it to you. The tool's instructions require your assistant to get your explicit confirmation before creating anything, and to use only information you provided or confirmed in the conversation.
4. Confirm. The assistant calls `create_digital_twin_lens` and returns:
   - **shareUrl**: your public lens page, live immediately
   - **claimUrl**: open it and sign up (free) to make the lens yours
   - **manageUrl**, **expiresAt**, **factCount**, and **suggestedPrompts**

No account is needed to create. The lens starts out **unclaimed**: live at its share URL, expiring after 30 days if never claimed. While it is unclaimed, your assistant can keep adding knowledge to it with `add_lens_knowledge`. Once you claim it, changes go through the app or the authenticated developer API.

5. Keep going in the same conversation. Ask your assistant to add your articles or pages:

```text
Add my last three blog posts to the lens, then check the ingestion
status and tell me when everything is ready.
```

The assistant calls `add_lens_knowledge` with the URLs, then polls `get_lens_status` until the knowledge counts show everything as ready. Open the share URL and ask your lens a question.

### With the REST API

Create an API key in the Mindola app, then create a lens seeded with knowledge in one call:

```bash
curl -s https://app.mindola.ai/api/v1/lenses \
  -H "Authorization: Bearer mnd_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product docs assistant",
    "greeting": "Hi, ask me anything about the product.",
    "knowledge": [
      { "type": "url", "content": "https://example.com/docs/getting-started", "title": "Getting started" },
      { "type": "text", "content": "Refunds are available within 30 days of purchase.", "title": "Refund policy" }
    ]
  }'
```

The response is `201` with `{ id, token, shareUrl, sourcesQueued }`. Ingestion runs in the background; poll `GET /api/v1/lenses/:id` until the knowledge counts show `ready`. Full reference in [docs/api.md](docs/api.md).

## 20 real-world use cases

1. **Coach**: an ask-me-anything page that answers from your method and captures leads when a question needs the real you.
2. **Open source maintainer**: developer documentation that answers questions with citations instead of making readers search.
3. **Course creator**: a course assistant students can ask at 2 a.m., grounded in the syllabus and lessons.
4. **Indie founder**: a customer support AI for a small product, answering from your docs and changelog.
5. **Job seeker**: a CV that answers recruiters' questions about your experience, in chat or voice.
6. **Small team**: internal documentation behind one link that the whole team can ask.
7. **Podcaster**: a persona built from episode notes and transcripts that listeners can question between episodes.
8. **Newsletter writer**: an archive readers can query instead of scrolling through years of issues.
9. **Conference speaker**: a page attendees can keep asking after the talk ends, seeded with your slides and notes.
10. **Consultant**: an AI expert page that qualifies inbound leads before the first call.
11. **Author**: a book companion that discusses your ideas and cites the chapters they come from.
12. **Agency**: a services page that pre-answers scope, process, and pricing questions from your own material.
13. **Teacher**: a study helper grounded in class materials, so answers match what was actually taught.
14. **Researcher**: a page that answers questions about your papers and points to the exact source.
15. **Product manager**: an FAQ bot for release notes, so "did you ship X yet" answers itself.
16. **Local business**: a website chatbot that answers hours, services, and policy questions from your own pages.
17. **HR team**: an onboarding assistant that answers from the employee handbook instead of a shared drive.
18. **Fitness trainer**: paid Q&A through Stripe, where visitors pay to ask your lens directly.
19. **Community manager**: a rules and guidelines bot that answers moderation questions consistently.
20. **Historical educator**: a public-domain figure brought to life, like the [Charles Darwin demo](https://mindola.ai/me/charles-darwin).

Ten of these are written out end to end in [examples/use-cases/](examples/use-cases/), each with a prompt to paste, the conversation to expect, and the final result.

## Example prompts

Paste any of these into Claude, Codex, Cursor, or ChatGPT once the server is connected.

```text
Create a Mindola lens for me. I'm a freelance UX designer with 10 years
of experience in fintech and healthcare. Interview me briefly to fill
the gaps, show me the profile, and only create it after I approve.
```

```text
Read the README and docs folder of this repository, then create a
Min