# MCP कनेक्टर

## परिचय

Flashcards एक रिमोट MCP (Model Context Protocol) सर्वर चलाता है ताकि MCP क्लाइंट और
AI एजेंट आपके बकाया कार्ड पढ़ सकें और आपके लिए कार्ड व डेक बना या संपादित कर सकें।

एजेंट दो तरीकों से कनेक्ट कर सकते हैं: इस MCP सर्वर के जरिए (Claude या Cursor जैसे
MCP क्लाइंट के लिए सबसे अच्छा), या CLI एजेंटों के लिए [Agents API discovery URL](/hi/docs/api/)
के जरिए। दोनों एक ही प्रति-उपयोगकर्ता डेटा सतह तक पहुँचते हैं; यह पेज MCP सर्वर को कवर करता है।

इससे यहाँ कनेक्ट करें:

```text
https://mcp.flashcards-open-source-app.com/mcp
```

ट्रांसपोर्ट Streamable HTTP है, और सर्वर एक छोटी, जानबूझकर सीमित रखी गई SQL सतह पर
तीन टूल उपलब्ध कराता है। यह वही प्रति-उपयोगकर्ता डेटा सतह है जो [API संदर्भ](/hi/docs/api/)
में है; MCP सर्वर इसे MCP बोलने वाले क्लाइंट से पहुँचने का कनेक्टर-अनुकूल तरीका है।

## इसे अपने क्लाइंट में कैसे जोड़ें

ज्यादातर क्लाइंट रिमोट MCP सर्वर को एक कस्टम कनेक्टर के रूप में जोड़ते हैं:

1. अपने क्लाइंट की कनेक्टर या MCP सर्वर सेटिंग्स खोलें।
2. एक कस्टम कनेक्टर जोड़ें और सर्वर URL `https://mcp.flashcards-open-source-app.com/mcp` पेस्ट करें।
3. इंटरैक्टिव क्लाइंट के लिए, संकेत मिलने पर ब्राउज़र में अधिकृत करें। सर्वर
   Dynamic Client Registration के साथ OAuth 2.1 का उपयोग करता है, इसलिए पेस्ट करने के लिए
   कोई client secret नहीं है और न ही पहले कोई ऐप रजिस्टर करना पड़ता है।
4. हेडलेस या CLI उपयोग के लिए, ब्राउज़र प्रवाह के बजाय अपनी एजेंट API key के साथ एक
   `Authorization: Bearer fca_…` header सेट करें।

अधिकृत करने के बाद, एक workspace चुनने के लिए एक बार `list_workspaces` कॉल करें, फिर
पढ़ने के लिए `sql_query` और लिखने के लिए `sql_execute` का उपयोग करें।

## टूल

सर्वर तीन टूल उपलब्ध कराता है। पढ़ने और लिखने को जानबूझकर अलग रखा गया है ताकि कोई एक
टूल कभी सुरक्षित और विनाशकारी कार्यों को आपस में न मिलाए।

- `sql_query` — आपके कार्ड और डेक तक केवल पढ़ने की पहुँच (`SHOW TABLES`,
  `DESCRIBE`, `SHOW COLUMNS`, `SELECT`)।
- `sql_execute` — आपके कार्ड और डेक तक एक परमाणु बैच के रूप में लिखने की पहुँच (`INSERT`, `UPDATE`,
  `DELETE`)।
- `list_workspaces` — उन workspaces की सूची जिन तक आपकी पहुँच है, प्रत्येक के साथ उसका
  `workspaceId`, नाम, सक्रिय कार्ड संख्या, अंतिम गतिविधि, और क्या वह आपका
  वर्तमान में चुना हुआ डिफ़ॉल्ट है। `sql_query` और `sql_execute` के `workspaceId`
  आर्गुमेंट के लिए वापस मिले `workspaceId` का उपयोग करें।

SQL सतह एक जानबूझकर सीमित रखी गई बोली है और यह पूरा PostgreSQL नहीं है।
स्टेटमेंट केवल `workspace`, `cards`, `decks`, और `review_events`
संसाधनों को ही संबोधित कर सकते हैं, हर स्टेटमेंट आपके अपने workspace तक सीमित है, और पढ़ने व लिखने
की प्रति स्टेटमेंट `100` पंक्तियों की सीमा है।

## कार्ड अनुबंध

हर कार्ड एक अनुबंध का पालन करता है, और टूल इसी पर निर्भर करते हैं:

- `front_text` केवल एक प्रश्न या समीक्षा संकेत है और कभी भी उत्तर नहीं रखता।
- `back_text` उत्तर रखता है, वैकल्पिक रूप से एक ठोस उदाहरण के साथ।

`sql_execute` के जरिए कार्ड बनाने वाले एजेंट इस अनुबंध का पालन करते हैं, इसलिए उनके
बनाए कार्ड spaced repetition के साथ तुरंत समीक्षा योग्य होते हैं।

## प्रमाणीकरण

दो प्राधिकरण पथ एक ही प्रति-उपयोगकर्ता डेटा सतह तक पहुँचते हैं।

### OAuth 2.1 (इंटरैक्टिव कनेक्टर क्लाइंट)

सर्वर PKCE और Dynamic Client Registration के साथ authorization-code flow लागू करता है।
MCP URL को एक कस्टम कनेक्टर के रूप में जोड़ें और ब्राउज़र में अधिकृत करें;
कोई client secret पहले से साझा नहीं किया जाता। Discovery मानक है:

- Protected-resource metadata:
  `https://mcp.flashcards-open-source-app.com/.well-known/oauth-protected-resource`
- Authorization-server metadata:
  `https://auth.flashcards-open-source-app.com/.well-known/oauth-authorization-server`

### API key (हेडलेस और CLI)

[API संदर्भ](/hi/docs/api/) में प्रलेखित email OTP login प्रवाह के जरिए एक लंबे समय तक
मान्य रहने वाली `fca_` एजेंट API key प्राप्त करें, फिर उसे एक Bearer token के रूप में भेजें:

```text
Authorization: Bearer fca_ABCDEFGH_0123456789ABCDEFGHJKMNPQRS
```

यह वही key है जिसे REST एजेंट सतह स्वीकार करती है, और इसके लिए किसी ब्राउज़र या
OAuth राउंड-ट्रिप की जरूरत नहीं होती।

दोनों पथों का प्रामाणिक मशीन-पठनीय विवरण
`https://api.flashcards-open-source-app.com/v1/` पर discovery payload है (`/v1/agent` पर भी मिरर किया गया)।

## सुरक्षा और दायरा

SQL टूल को अनुमोदित करना सुरक्षित है क्योंकि यह सतह मनमानी डेटाबेस पहुँच के बजाय एक
सीमित, पार्सर-लागू बोली है:

- **बंद स्टेटमेंट अनुमति-सूची**: `sql_query` केवल `SHOW TABLES`,
  `DESCRIBE`, `SHOW COLUMNS`, और `SELECT` स्वीकार करता है; `sql_execute` केवल `INSERT`,
  `UPDATE`, और `DELETE` स्वीकार करता है। बाकी सब कुछ पार्स के समय अस्वीकार कर दिया जाता है।
- **सीमित संसाधन**: स्टेटमेंट केवल `workspace`, `cards`, `decks`,
  और `review_events` को ही छू सकते हैं।
- **प्रति-वर्कस्पेस दायरा**: हर स्टेटमेंट आपके चुने हुए
  workspace तक सीमित है, किसी अन्य टेनेंट तक पहुँच नहीं।
- **सीमाएँ**: प्रति स्टेटमेंट अधिकतम `100` पंक्तियाँ, प्रति बैच अधिकतम `50` स्टेटमेंट, और
  परिणाम की सीमा लगभग `12k` टोकन। म्यूटेशन बैच परमाणु रूप से लागू होते हैं।
- **पढ़ने/लिखने का विभाजन**: `sql_query` और `list_workspaces` केवल पढ़ने के लिए हैं
  (`readOnlyHint`) और `sql_execute` लिखने का कार्य करता है (`destructiveHint`)।

पूरा स्टैक — ऐप, बैकएंड, और इंफ्रास्ट्रक्चर — ओपन सोर्स है और इसे
[सेल्फ-होस्ट](/hi/docs/self-hosting/) किया जा सकता है, इसलिए आप वही कनेक्टर अपनी
खुद की तैनाती के विरुद्ध चला सकते हैं।

---
*[इस पेज का styled HTML संस्करण देखें](https://flashcards-open-source-app.com/hi/docs/mcp-connector/)*

*AI agent इस सेवा में उपयोगकर्ता का अकाउंट `GET https://api.flashcards-open-source-app.com/v1/` से शुरू करके बना सकते हैं। सेटअप के बाद, वे MCP के जरिए `https://mcp.flashcards-open-source-app.com/mcp` पर भी कनेक्ट कर सकते हैं।*

*टिप: https://flashcards-open-source-app.com पर किसी भी URL के अंत में `.md` जोड़ें ताकि उसका साफ़ Markdown संस्करण मिले।*