DEV Community: BBT हिन्दी

osFoundry की MCP tool list Codex में कितने token खाती है, और इसे हर project के लिए कैसे छोटा करें?

BBT — Sat, 07 Nov 2026 14:49:39 +0000

यह वह call है जो कोई MCP client handshake के ठीक बाद भेजता है। इसे 2026-11-06 को Tokyo के एक Mac से curl के ज़रिए osFoundry के server पर भेजा गया। इसके लिए किसी token की ज़रूरत नहीं होती:

$ curl -s -D - -X POST https://api.osfoundry.io/api/v1/external-mcp \
    -H 'content-type: application/json' \
    -H 'accept: application/json, text/event-stream' \
    -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

HTTP/2 200
content-type: application/json
content-length: 45368

{"jsonrpc":"2.0","id":2,"result":{"tools":[ …59 tools… ]}}

59 में से एक entry:

{"name": "read_note_tab",
 "title": "Read one Note tab",
 "description": "Read a selected Note, Markdown, Slides, Sheet, Mermaid, Board, Whiteboard, Design, or Artifacts tab by instance ID. Use list_note_attachments for Files and Sources.",
 "inputSchema": {"type": "object",
                 "properties": {"note_id": {"type": "string"}, "tab_id": {"type": "string"}},
                 "required": ["note_id", "tab_id"], "additionalProperties": false},
 "annotations": {"title": "Read one Note tab", "readOnlyHint": true,
                 "openWorldHint": false, "destructiveHint": false},
 "securitySchemes": [{"type": "oauth2", "scopes": ["osfoundry:read"]}]}

Codex CLI इस server से एक [mcp_servers.osfoundry] table और एक url के ज़रिए जुड़ता है। जब तक client इनमें से कुछ को defer न करे, Codex का model को भेजा गया हर request इन 59 declarations को किसी न किसी रूप में साथ ले जाता है। नीचे वही सवाल हैं जो आपके सामने तब आते हैं जब आप तय करते हैं कि इनमें से कितने साथ जाने चाहिए।

पहले turn से पहले Codex क्या fetch करता है?

एक ही URL पर तीन POST: initialize, notifications/initialized notification, और tools/list। Live server इनका जवाब ऐसे देता है:

Request	Status	Body
`initialize`	200	308 bytes: protocol `2025-06-18`, `osfoundry 0.1.0`, `tools.listChanged: false`, instructions
`notifications/initialized`	202	खाली
`tools/list`	200	45,368 bytes, 59 tools
बिना token के `tools/call`	401	`resource_metadata` के साथ `WWW-Authenticate`

listChanged: false का मतलब है कि session के बीच में list बदलने पर server कोई सूचना नहीं देगा। Startup पर Codex को जो list मिलती है, पूरे session के लिए वही list रहती है।

instructions string 125 characters की है: "Use list_granted_resources first. Every Note edit must use the exact tab ID. Local-only data is unavailable to cloud clients." OpenAI के Codex docs के मुताबिक Codex इस field को पूरे server के लिए guidance के तौर पर पढ़ता है, और इसके पहले 512 characters अपने आप में पूरे होने चाहिए। यह string उस limit से काफ़ी नीचे है।

401 वह जगह है जहाँ से OAuth शुरू होता है। वह हिस्सा, और osFoundry हर call पर access क्यों check करता है, उसी endpoint पर Claude की तरफ़ से लिखे गए एक अलग post में cover किया गया है। यहाँ सिर्फ़ catalogue मायने रखता है।

59 tools कितने token के होते हैं?

Model तक raw JSON नहीं पहुँचता। Codex हर MCP tool को एक function declaration में बदलता है। Model को name, description और input schema चाहिए। title, annotations और securitySchemes protocol metadata हैं जिन्हें client ख़ुद इस्तेमाल करता है। OpenAI यह publish नहीं करता कि उसकी तरफ़ tool declarations कैसे गिने जाते हैं, इसलिए नीचे के numbers payload गिनते हैं, bill नहीं।

tiktoken 0.14.0 और o200k_base encoding से, compact JSON पर नापा गया:

क्या	Token
Raw `tools/list` result, सारे fields	10,494
59 declarations (`mcp__osfoundry__` prefix वाला name, description, schema)	7,609
इनमें से descriptions	2,194
इनमें से input schemas	4,118
इनमें से `mcp__osfoundry__` prefixes	413
Client में ही रहने वाला metadata (title, annotations, securitySchemes)	3,590

एक declaration का median 116 token है। सबसे बड़ा edit_note_tab है, 336 पर, फिर send_channel_message (237) और upload_linked_chat_artifact (233)। सबसे छोटा list_granted_resources है, 57 पर।

Scope के हिसाब से: 30 osfoundry:read tools मिलाकर 2,906 token, 26 osfoundry:write tools 4,378, और 3 osfoundry:run tools 329। Write tools प्रति tool ज़्यादा महँगे हैं क्योंकि उनमें expected_version, idempotency_key और लिखा जाने वाला content होता है।

लगभग 7,600 token हर request के आगे बैठे रहते हैं, चाहे model osFoundry को call करे या न करे। Cached prompt prefixes की वजह से यह जितना सुनाई देता है उससे सस्ता पड़ता है। फिर भी यह context की जगह घेरता है, और जब model तय करता है कि कौन-सा tool सही है, तो 59 names उसका ध्यान खींचने के लिए आपस में होड़ करते हैं।

Codex `enabled_tools` को कहाँ apply करता है?

ये keys OpenAI के Codex MCP page पर documented हैं: enabled_tools एक allow list है, और disabled_tools एक deny list जो "applied after enabled_tools" होती है। Implementation openai/codex repository में codex-rs/codex-mcp/src/tools.rs में है:

pub(crate) fn allows(&self, tool_name: &str) -> bool {
    if let Some(enabled) = &self.enabled
        && !enabled.contains(tool_name)
    {
        return false;
    }

    !self.disabled.contains(tool_name)
}

pub(crate) fn filter_tools(tools: Vec<ToolInfo>, filter: &ToolFilter) -> Vec<ToolInfo> {
    tools
        .into_iter()
        .filter(|tool| filter.allows(&tool.tool.name))
        .collect()
}

इसके दो नतीजे हैं। पहला, filter tool.tool.name यानी raw MCP name से compare करता है, इसलिए config.toml में आप read_note_tab लिखते हैं, mcp__osfoundry__read_note_tab नहीं। Prefix बाद में उसी file में जोड़ा जाता है, जब model को दिखने वाले names बनाए जाते हैं। दूसरा, set lookup कभी fail नहीं होता। जो name tools/list में मौजूद नहीं है, वह किसी से match नहीं करता और कोई error भी नहीं देता।

Filter tools/list आने के बाद client में चलता है। इससे prompt छोटा होता है, download नहीं, और server को इसके बारे में कुछ पता नहीं होता।

Client side को दोबारा बनाना

जिस Mac (Apple M1) पर यह नापा गया, उस पर codex binary install नहीं है। catalog.py यहाँ Codex के startup की जगह काम करता है। यह 92 lines का है और uv run --python 3.12 --with tiktoken से चलता है। यह एक TOML file से [mcp_servers.*] tables पढ़ता है, http.client के ज़रिए live endpoint पर तीनों requests भेजता है, raw names पर वही allow-फिर-deny rule लगाता है, mcp__osfoundry__<tool> declarations बनाता है और उन्हें गिनता है:

kept = [t for t in tools if (allow is None or t["name"] in allow) and t["name"] not in deny]
decls = [model_decl("osfoundry", t) for t in kept]
unknown = sorted(((allow or set()) | deny) - names)

Profile file में हर configuration के लिए एक table है। असली config.toml में एक ही [mcp_servers.osfoundry] table होगी, global या हर repository के लिए अलग:

[mcp_servers.notes_kb_records]
url = "https://api.osfoundry.io/api/v1/external-mcp"
enabled_tools = [
  "list_granted_resources", "list_project_resources", "list_note_tabs",
  "read_note_tab", "read_sheet_range", "search_knowledge_base",
  "read_knowledge_article", "list_record_items", "read_record_item",
]

[mcp_servers.deny_list]
url = "https://api.osfoundry.io/api/v1/external-mcp"
disabled_tools = ["request_session_run", "run_graph_session", "cancel_graph_run",
                  "propose_gitnest_work", "…the other propose_ tools…",
                  "join_agent_network", "send_agent_message", "wait_for_messages",
                  "list_agents", "set_status", "claim_connected_profile"]

[mcp_servers.typo]
url = "https://api.osfoundry.io/api/v1/external-mcp"
enabled_tools = ["list_granted_resources", "list_project_resources",
                 "read_note", "search_knowledge_base"]

Output:

$ uv run --python 3.12 --with tiktoken python catalog.py profiles.toml --runs 10
status (200, 202, 200)  initialize 308 B  tools/list 45368 B  59 tools  instructions 125 chars
raw tools/list result: 10494 tokens (o200k_base)

profile                  tools   bytes  tokens  unknown names
all_59                      59   33559    7609  -
read_only                   30   13181    2906  -
notes_kb_records             9    3937     881  -
coding_project              16    7245    1604  -
deny_list                   40   20943    4693  -
typo                         3    1449     309  read_note

read_only में वे सारे tools हैं जिन पर readOnlyHint: true है। coding_project में नौ Note/KB/Record readers के साथ पाँच GitNest readers, edit_record_item और post_session_note हैं। deny_list वे 19 tools हटाती है जिनका local checkout वाले coding assistant के लिए ज़्यादा काम नहीं: तीन run tools, दस propose_… tools और छह agent-network व profile tools।

59 tools से घटाकर नौ readers पर आने से declarations 7,609 से 881 token पर आ जाते हैं, यानी 88% कम। Deny list सिर्फ़ 4,693 तक पहुँचती है, क्योंकि write tools ही महँगे हैं और यह उनमें से ज़्यादातर को रहने देती है। Allow list ज़्यादा predictable choice है। Server नए tools जोड़े तब भी यह छोटी ही रहती है, और इसे चुनने की असली वजह यही है।

typo वाली row वह failure है जो आपको सच में देखने को मिलेगी। read_note कोई tool नहीं है (read_note_tab है), इसलिए profile में तीन ही tools बचते हैं, और कोई शिकायत नहीं करता। Codex आराम से Note की list दिखा देगा, लेकिन फिर उसे खोलने का कोई तरीका नहीं होगा। यह simulator unknown names print करता है। Docs और filter code से जितना दिखता है, Codex ऐसा नहीं करता।

Handshake में कितना समय लगता है?

catalog.py --runs 10 ने तीनों requests का शुरू से आख़िर तक समय दो बार नापा, एक बार एक ही TLS connection पर और एक बार हर request के लिए नए connection के साथ:

Batch (हर एक n=10)	`initialize` median	`tools/list` median	पूरा startup median	min–max
एक connection, batch 1	482 ms	826 ms	1,515 ms	1,034–2,899 ms
नया connection, batch 1	521 ms	704 ms	1,715 ms	1,122–3,107 ms
एक connection, batch 2	454 ms	828 ms	1,441 ms	741–1,915 ms
नया connection, batch 2	432 ms	478 ms	1,257 ms	1,088–1,557 ms

Connection reuse से कोई consistent फ़र्क़ नहीं पड़ा। Runs के बीच का variation असर से ज़्यादा था। Filtering इस number को बिल्कुल नहीं बदलती, क्योंकि Codex दोनों हालात में पूरी list download करता है।

Codex की तीन documented settings इस number से जुड़ती हैं। startup_timeout_sec का default 10 seconds है, और यहाँ सबसे धीमा run 3.1 s का था। mcp_optional_startup_grace_ms का default 1,000 ms है और docs के मुताबिक यह "controls how long Codex waits for optional MCP servers when building the initial tool catalog"। यहाँ नापा गया हर startup इससे ज़्यादा समय ले गया। अगर osFoundry के tools पहले turn से ही मौजूद होने चाहिए, तो documented विकल्प हैं required = true, जो startup को server का इंतज़ार करवाता है और server तैयार न हो तो fail हो जाता है, और startup_readiness = "catalog", जो live connection बनने तक एक valid cached catalogue से startup पूरा होने देता है। Tool calls के लिए फिर भी live connection चाहिए।

Annotations से आपको क्या मिलता है?

default_tools_approval_mode में auto, prompt, writes या approve दिया जा सकता है, और "the writes mode prompts for tools that aren't marked read-only"। osFoundry अपने 59 में से 30 tools पर readOnlyHint: true लगाता है। writes के साथ Codex इन्हें बिना पूछे चलाता है और बाकी 29 के लिए पूछता है, यानी वही बँटवारा जो आप हाथ से करते। किसी एक tool के लिए tools.<tool>.approval_mode default को override करता है, और tools.<tool>.output_token_limit यह limit करता है कि एक tool का result context में कितना जोड़ सकता है।

OAuth layer पर scope भी इसी तरह काम करता है। अगर config में scopes set है तो Codex उसे इस्तेमाल करता है। वरना वह server के challenge या उसके protected-resource metadata से scopes लेता है, और osFoundry की list में osfoundry:read, osfoundry:write, osfoundry:run और osfoundry:models हैं। scopes = ["osfoundry:read"] के साथ token सिर्फ़ पढ़ने के लिए issue होता है, और हर write tool अपने securitySchemes में osfoundry:write declare करता है, चाहे enabled_tools में कुछ भी लिखा हो।

असली filter कौन-सा है?

तीन filters हैं, और उनमें से सिर्फ़ एक security boundary है।

config.toml में enabled_tools / disabled_tools तय करते हैं कि model को क्या offer किया जाए। जो भी इस file को edit कर सकता है, वह इसे बदल सकता है।
osFoundry के Connected tab में Tools checklist, connection पर allowed_tools के रूप में store होती है। null का मतलब है "हर मौजूदा और आने वाला supported tool"। इसे owner set करता है, और कोई local file इसे बढ़ा नहीं सकती।
Project membership और हर call पर होने वाला access check तय करते हैं कि कोई भी tool किस चीज़ को छू सकता है। बिना किसी project वाले connection पर पूरी tool list भी कुछ नहीं पढ़ पाती।

Client filter prompt की साफ़-सफ़ाई के लिए है। इसे token बचाने और model के choices के लिए इस्तेमाल करें, और permissions के लिए बाकी दो का।

अगर आप इसे ख़ुद wire up करें

दर्जनों tools वाले server के लिए disabled_tools की जगह enabled_tools चुनें। यह token में छोटा है और server नए tools जोड़े तब भी stable रहता है।
Raw MCP names लिखें, और server update होने पर अपनी list को एक fresh tools/list से diff करें। Unknown names चुपचाप fail होते हैं।
scopes को explicitly set करें, ताकि token में config के इरादे से ज़्यादा कुछ न हो।
default_tools_approval_mode = "writes" को ऐसे server के साथ इस्तेमाल करें जो readOnlyHint ईमानदारी से set करता हो। Prompt का बँटवारा उतना ही अच्छा है जितने annotations।
अगर server एक second या उससे ज़्यादा दूर है, तो 1,000 ms grace default के भरोसे छोड़ने के बजाय required = true और startup_readiness = "catalog" में से एक चुनें।
Server के instructions को 512 characters से कम और अपने आप में पूरा रखें। यह tool list की तरह हर session के साथ भेजा जाता है।

Tool list का आम तौर पर context budget से क्या रिश्ता है, यह osFoundry के context window glossary page पर है।

Custom connector से Claude chat को अपने osFoundry projects से कैसे जोड़ें

BBT — Sat, 07 Nov 2026 13:34:20 +0000

इस guide के आख़िर तक, claude.ai पर एक साधारण Claude conversation आपके किसी osFoundry project के Notes, knowledge bases और Records खोल सकेगी, उन्हीं के आधार पर जवाब दे सकेगी, और उस project के discussion channel में post कर सकेगी। आपकी approval के साथ वह इन्हें edit भी कर सकती है। Claude में आप हमेशा की तरह signed in रहते हैं। हर tool call पर osFoundry तय करता है कि वह chat किन चीज़ों को छू सकती है, और हर call osFoundry में connection के Recent activity में दर्ज होता है। ChatGPT भी इसी तरह, इसी server address से जुड़ता है।

कौन क्या करता है

	Claude की तरफ़	osFoundry की तरफ़
Login	आपका Claude account, बिना बदलाव	आपका osFoundry account connection को एक बार approve करता है, एक workspace के लिए
Model कौन चलाता है	Claude, उसी chat में जो आप पहले से इस्तेमाल करते हैं	कुछ नहीं। इस रास्ते पर न कोई model है, न कोई provider key
Tools कहाँ चलते हैं	Claude tool call भेजता है	`api.osfoundry.io` पहले access check करता है, फिर उसे चलाता है
किन चीज़ों तक पहुँच है	जो भी server लौटाए	वे projects जिनमें आपने connection जोड़ा, और वे channels जिनमें आपने उसे invite किया
Approvals	Claude का अपना tool-permission prompt	GitNest और Room के बदलाव "Needs your approval" में इंतज़ार करते हैं
Data कहाँ रहता है	जवाब आपकी Claude chat में रहता है	Notes, records और articles osFoundry में रहते हैं। Local-only items कभी device से बाहर नहीं जाते

Setup

1. osFoundry में connection बनाएँ

osFoundry में header के key icon पर click करें और Connected tab खोलें। Panel का title "Connected agents" है और यह दिखाता है कि आप किस workspace में हैं। "Connect in three steps" के नीचे:

Assistant: Claude चुनें
Display name: कोई भी नाम जिसे आप बाद में पहचान सकें, जैसे Claude research
Add assistant (assistant जोड़ें) पर click करें

नए connection पर "Setup pending. This assistant cannot read or change anything yet." दिखता है। उसके बगल वाले Copy button से Server address copy करें:

https://api.osfoundry.io/api/v1/external-mcp

उदाहरण: Add assistant के बाद Connected tab, server address और pending connection के साथ

2. इसे Claude में custom connector के रूप में जोड़ें

Claude में Customize → Connectors खोलें और उस URL से एक custom connector जोड़ें। Team या Enterprise plan पर, पहले organization owner इसे Organization settings → Connectors में जोड़ता है, फिर हर member connect करता है। Remote MCP connectors के लिए Anthropic के steps Claude की custom connector guide में हैं।

Connect पर click करते ही Claude osFoundry का sign-in अपने आप ढूंढ लेता है। आपको कोई client ID या key paste नहीं करनी पड़ती।

3. एक workspace approve करें

आपका browser https://osfoundry.io/external-assistant-authorize पर पहुँचता है, जिस page का title "Connect an agent" है। यह assistant client और वह host दिखाता है जहाँ वह वापस जाएगा, फिर ये चीज़ें पूछता है:

Workspace to connect: एक workspace। दूसरे workspace के लिए अलग connection चाहिए।
Requested capabilities, आसान शब्दों में: "Read supported resources in projects you add", "Change supported resources where you have edit access", "Run sessions where you grant a runner role"।
Connection: "Use pending: Claude research" चुनें ताकि यह step 1 वाले connection से जुड़ जाए, या "Create a new connection" रहने दें।
"I approve connecting this assistant to " पर tick करें, फिर Connect।

आप वापस Claude पर भेज दिए जाते हैं। Connection live है, लेकिन अभी उसे कुछ नहीं दिखता। नया connection zero projects से शुरू होता है।

4. इसे किसी project में जोड़ें

फिर से key icon → Connected में जाकर connection चुनें। अब वहाँ "Connected." लिखा है। Projects के नीचे कोई project चुनें और Add to project पर click करें।

उदाहरण: Project में जोड़ा गया connection, नीचे उसकी linked chat के साथ

इससे उस project के supported synced content तक access मिल जाता है: Notes, knowledge bases, Record channels, cloud Rooms, उस project को assign की गई GitNest repositories, और project का discussion channel। बाद में project में जोड़ा गया content भी इसमें शामिल होता है। साधारण Message channels अलग हैं। जिस-जिस channel में chat को पढ़ना और जवाब देना हो, उसके लिए Message channels → Choose a Message channel → Invite इस्तेमाल करें।

Tools section में लिखा है "All supported tools are on by default."। जो tools आप इस connection को नहीं देना चाहते, उनका tick हटाएँ और Save tools पर click करें।

उदाहरण: Claude connection की Tools checklist, default में सब on

5. Chat में इसे on करें

किसी Claude conversation में + menu → Connectors खोलें और osFoundry connector enable करें। फिर सीधी भाषा में पूछें।

एक असली run

नीचे का prompt और जवाब एक demo project का Example content है। Tool names और argument names वही हैं जो live server tools/list में बताता है। claude.ai में calls connector के नाम के नीचे दिखती हैं। अगर आप यही URL Claude Code में osfoundry नाम से जोड़ते हैं, तो वही tools mcp__osfoundry__list_project_resources वगैरह के रूप में दिखते हैं।

उदाहरण

आप: osFoundry से बताओ, Q3 launch checklist में अभी क्या-क्या बाकी है?
     Support KB में कुछ उससे उल्टा लिखा हो तो check करो, फिर
     "pricing page" record को Ready mark कर दो।

Claude → list_granted_resources {}
       ← 1 connected project: "Launch Q3" (workspace)
Claude → list_project_resources {"project_id": "…", "resource_type": "note", "search": "checklist"}
       ← Note "Q3 launch checklist"
Claude → list_note_tabs {"note_id": "…"}
       ← tabs: Note (text), Sheet "Owners"
Claude → read_note_tab {"note_id": "…", "tab_id": "…"}
       ← 9 items, 3 unchecked
Claude → search_knowledge_base {"knowledge_base_id": "…", "query": "refund window"}
       ← article "Refund policy" (2 दिन पहले update हुआ)
Claude → read_record_item {"record_channel_id": "…", "item_id": "…"}
       ← "pricing page", status Draft, version …
Claude → edit_record_item {"record_channel_id": "…", "item_id": "…",
                           "values": {"status": "Ready"},
                           "expected_version": "…", "idempotency_key": "…"}
       [Claude आपसे यह tool call allow करने को कहता है → Allow]
       ← saved, नया version …

Claude: तीन items बाकी हैं: press embargo की तारीख, FAQ translation,
        और pricing page पर refund वाली line। Checklist में 14 दिन
        लिखा है; KB article "Refund policy" में 30। Pricing page
        record को मैंने Ready mark कर दिया है।

उस transcript की दो बातें जान-बूझकर रखी गई हैं। edit_record_item को वह version चाहिए जो read_record_item ने लौटाया था, इसलिए अगर बीच में record बदल गया हो तो वह overwrite होने के बजाय reject हो जाता है। दोबारा भेजा गया वही idempotency_key पहला result लौटाता है, इसलिए retry किया गया call दो बार write नहीं करता।

सीमा कहाँ है

osFoundry आपकी Claude chats नहीं खोल सकता। MCP connection Claude को osFoundry tools तब call करने देता है जब Claude ऐसा तय करे। उल्टी दिशा में osFoundry के पास कोई API नहीं है जिससे वह किसी personal conversation को list करे, पढ़े या शुरू करे। Chat को project से link करने वाला tool (link_current_chat) वह label लेता है जो chat अपने बारे में ख़ुद बताती है, और osFoundry उसे verified identity नहीं, बल्कि routing hint मानता है। इसी वजह से Claude को osFoundry से कोई background notification नहीं मिलता। वह तभी काम करता है जब आप conversation खोलकर कुछ पूछते हैं।

Local-only data local ही रहता है। Server अपने initialize reply में ख़ुद यह कहता है: "Local-only data is unavailable to cloud clients."। Local Rooms, local Graph sessions और कभी sync न हुआ content connection को नहीं दिखता। Desktop Graph sessions share करना उसी tab में एक अलग switch है, और इसके लिए desktop app खुला और signed in होना चाहिए।

Access हर call पर check होता है, हर sign-in पर नहीं। हर call को connection के status, उसके workspace, project की मौजूदा membership, item इस समय किस project में है, और उस item पर आपके अपने role से मिलाया जाता है। किसी Note को दूसरे project में move करें, project हटा दें, या Revoke connection पर click करें, तो अगला call refuse हो जाता है। Edits के लिए यह भी ज़रूरी है कि आपके पास, यानी connection approve करने वाले व्यक्ति के पास, अब भी edit rights हों।

कुछ writes proposals बन जाते हैं। GitNest work, change sets, file imports, pull requests और Room app installs propose_… tools से होकर जाते हैं। ये Connected tab में "Needs your approval" के नीचे इंतज़ार करते हैं, जहाँ Approve या Decline चुनने से पहले आप target repository या Room और files देख सकते हैं। Claude को आपका Git provider token या कोई secret value कभी नहीं मिलती।

Message channels के लिए invitation ज़रूरी है। किसी project में होने से सिर्फ़ उसी project का discussion channel खुलता है। बाक़ी हर channel के लिए अलग से Invite चाहिए, और private channel में उसके owner को invite करना होता है।

आगे क्या

उसी project में एक knowledge base जोड़ें और Claude से ऐसा सवाल पूछें जिसका जवाब आप आम तौर पर उसी से देते हैं, जैसे "हमारी KB refunds के बारे में क्या कहती है, article के नाम के साथ?"। search_knowledge_base article ID और उसके last update का समय लौटाता है, ताकि आप source check कर सकें। osFoundry की knowledge bases कैसे organised हैं, यह knowledge bases page पर है।

Claude का custom connector osFoundry का OAuth server कैसे ढूंढता है, और हर call पर access क्यों check होता है?

BBT — Fri, 06 Nov 2026 10:52:06 +0000

जब कोई remote MCP client बिना token के osFoundry का कोई tool call करता है, तो उसे यह मिलता है। यह request 2026-11-06 को Tokyo में एक Mac से curl से भेजी गई थी:

$ curl -s -D - -X POST https://api.osfoundry.io/api/v1/external-mcp \
    -H 'content-type: application/json' \
    -H 'accept: application/json, text/event-stream' \
    -d '{"jsonrpc":"2.0","id":3,"method":"tools/call",
         "params":{"name":"list_project_resources","arguments":{}}}'

HTTP/2 401
www-authenticate: Bearer resource_metadata="https://api.osfoundry.io/.well-known/oauth-protected-resource/api/v1/external-mcp", error="invalid_token", error_description="Connect osFoundry to continue"

{"jsonrpc":"2.0","id":3,"result":{"isError":true,
  "content":[{"type":"text","text":"Authentication required"}],
  "_meta":{"mcp/www_authenticate":["Bearer resource_metadata=\"https://api.osfoundry.io/.well-known/oauth-protected-resource/api/v1/external-mcp\", ..."]}}}

Claude के custom connector को, या ChatGPT के developer mode वाले MCP connection को, sign-in page ढूंढने के लिए बस यही एक header काफ़ी है। User को सिर्फ़ URL paste करना होता है। नीचे जो कुछ भी है वह live endpoint पर बिना authentication वाली requests से लिया गया है, साथ में Python का एक छोटा rebuild है जो locally चलाया गया। यह rebuild वह हिस्सा मापता है जो curl नहीं दिखा सकता: sign-in के बाद access के साथ क्या होता है।

Token मिलने से पहले client को क्या दिखता है?

तीन calls, तीन अलग जवाब:

Request	Status	क्या वापस आता है
`initialize`	200	protocol `2025-06-18`, server `osfoundry 0.1.0`, साथ में instructions
`tools/list`	200	59 tools, 45,368 bytes
`tools/call`	401	`WWW-Authenticate`, जो resource metadata की ओर इशारा करता है
endpoint पर `GET`	405	GET पर कोई SSE stream नहीं

Handshake और tool catalogue public हैं। सिर्फ़ tool call करने के लिए token चाहिए। इससे host किसी के sign in करने से पहले ही user को दिखा सकता है कि कौन-कौन से tools मौजूद हैं। Catalogue में कोई user data नहीं है, और initialize में मौजूद instructions string generic है:

Use list_granted_resources first. Every Note edit must use the exact tab ID.
Local-only data is unavailable to cloud clients.

tools/list का हर tool बताता है कि उसे कौन-सा OAuth scope चाहिए और क्या वह सिर्फ़ read करता है:

{"name": "edit_record_item",
 "annotations": {"readOnlyHint": false, "destructiveHint": true, "openWorldHint": false},
 "securitySchemes": [{"type": "oauth2", "scopes": ["osfoundry:write"]}]}

59 tools में से: 30 को osfoundry:read चाहिए और वे readOnlyHint: true से marked हैं, 26 को osfoundry:write चाहिए, और 3 को osfoundry:run चाहिए (request_session_run, run_graph_session, cancel_graph_run)। Host readOnlyHint के आधार पर तय कर सकता है कि किन calls पर approval prompt दिखाना है।

401 उसे कहां भेजता है?

resource_metadata RFC 9728 (OAuth Protected Resource Metadata) को follow करता है। Well-known suffix host के ठीक बाद आता है, और resource path उसके पीछे जुड़ता है। इसे resource URL के आख़िर में नहीं जोड़ा जाता:

GET /.well-known/oauth-protected-resource/api/v1/external-mcp   200
GET /.well-known/oauth-protected-resource                       200 (same document)
GET /api/v1/external-mcp/.well-known/oauth-protected-resource   404

{"resource": "https://api.osfoundry.io/api/v1/external-mcp",
 "authorization_servers": ["https://api.osfoundry.io"],
 "scopes_supported": ["osfoundry:read", "osfoundry:write", "osfoundry:run", "osfoundry:models"]}

अगर आप client हाथ से बना रहे हैं, तो सबसे पहली गलती आप यही 404 वाली करेंगे। URL ख़ुद बनाने की बजाय header से पढ़िए।

Authorization server अपने बारे में क्या बताता है?

/.well-known/oauth-authorization-server (RFC 8414):

{"issuer": "https://api.osfoundry.io",
 "authorization_endpoint": "https://api.osfoundry.io/api/v1/external-oauth/authorize",
 "token_endpoint": "https://api.osfoundry.io/api/v1/external-oauth/token",
 "registration_endpoint": "https://api.osfoundry.io/api/v1/external-oauth/register",
 "grant_types_supported": ["authorization_code", "refresh_token"],
 "token_endpoint_auth_methods_supported": ["none"],
 "code_challenge_methods_supported": ["S256"],
 "authorization_response_iss_parameter_supported": true}

इसे फ़ैसलों की एक chain की तरह पढ़िए। इसमें registration_endpoint है, इसलिए host ख़ुद को register कर सकता है (dynamic client registration) और user को कभी client ID से जूझना नहीं पड़ता। Token auth none है, यानी host एक public client है जिसके पास client secret नहीं है, और S256 वाला PKCE ही code को उस client से बांधता है जिसने उसे मांगा था। Authorization response में iss उस गड़बड़ी से बचाता है जब कोई host कई authorization servers से बात कर रहा हो।

Authorize step browser को osFoundry के consent page https://osfoundry.io/external-assistant-authorize पर भेजता है। वहां user ठीक एक workspace चुनता है और "I approve connecting this assistant to …" (मैं इस assistant को … से जोड़ने की अनुमति देता हूं) पर tick करता है। Approval में सिर्फ़ एक workspace का नाम होता है, और कुछ नहीं। नए connection में कोई project नहीं होता। Owner उन्हें बाद में app में जोड़ता है (key icon → Connected → Add to project)।

सिर्फ़ scope काफ़ी क्यों नहीं है?

Scope उसी समय तय हो जाता है जब token mint होता है। osfoundry:write बताता है कि connection write वाले actions कर सकता है। यह नहीं बताता कि कौन-सा Note, और इसे यह पता भी नहीं हो सकता कि वह Note दस मिनट पहले किसी दूसरे project में चला गया। osFoundry के design notes में लिखा है कि हर call पर क्या दोबारा पढ़ा जाता है: connection status, workspace, project membership, resource का मौजूदा project और ACL, channel membership या session role, tool, और OAuth scope। जिस व्यक्ति ने connection approve किया था, उसके पास उस item पर अभी भी edit rights होने चाहिए। हटाना या reassign करना "तुरंत लागू होता है"।

दूसरा रास्ता यह है कि project list को token में डाल दिया जाए, या token को key बनाकर cache में रख दिया जाए, और expiry तक उस पर भरोसा किया जाए। यह लिखने में सस्ता है। नीचे वाला rebuild दोनों को implement करता है ताकि behaviour का फ़र्क़ मापा जा सके।

Rebuild

इसमें कोई Claude binary शामिल नहीं है। client.py host का रोल निभाता है और server.py MCP server का। दोनों सिर्फ़ standard library इस्तेमाल करते हैं, मिलाकर लगभग 280 lines, और Apple M1 पर Python 3.9.6 में चलाए गए। Server plain HTTP JSON-RPC पर initialize, tools/list और tools/call implement करता है, साथ में दोनों well-known documents, /authorize (consent page एक workspace के लिए अपने आप approve हो जाता है), और S256 PKCE के साथ /token। कुछ /admin/* routes Connected tab में owner के clicks की जगह लेते हैं।

हर tool से पहले चलने वाला check:

def access(token_info, tool, note_id):
    if TOOL_SCOPE[tool] not in token_info["scopes"]:
        return "insufficient_scope"
    if CHECK == "token_only":                     # design B: trust issue-time state
        ok = note_id is None or NOTES[note_id]["project"] in token_info["projects_at_issue"]
        return None if ok else "not_in_project"
    conn = CONNECTIONS.get(token_info["connection"])
    if not conn or conn["status"] != "active":
        return "connection_revoked"
    if note_id is None:
        return None
    note = NOTES.get(note_id)
    if not note or note["workspace"] != conn["workspace"]:
        return "not_found"
    if (token_info["connection"], note["project"]) not in PROJECT_MEMBERS:
        return "not_in_project"
    return None

Client बिना token के शुरू होता है। वह एक tool call करता है, 401 लेता है, WWW-Authenticate से resource_metadata parse करता है, दोनों metadata documents fetch करता है, नए PKCE verifier के साथ authorize और token चलाता है, और फिर scenario से गुज़रता है:

$ CHECK=per_call python3 server.py &  python3 client.py 8767
discovery: first call -> 401, metadata /.well-known/oauth-protected-resource/mcp, 5 round trips, 11.3 ms
1 fresh connection, no project yet           200 OK   []
2 after owner adds project A                 200 OK   ["note-a1"]
3 read note in A                             200 OK   "Q3 launch checklist"
4 read note in B (never added)               200 DENY not_in_project
5 write with a read-only token               403 DENY insufficient_scope
6 write with read+write token                200 OK   "saved"
7 same read after note moved to B            200 DENY not_in_project
8 same read after owner removes project A    200 DENY not_in_project
9 same read after revoke                     200 DENY connection_revoked

वही client CHECK=token_only के ख़िलाफ़। यहां token में उसके पिछले refresh के समय की project list होती है:

7 same read after note moved to B            200 DENY not_in_project
8 same read after owner removes project A    200 OK   "Q3 launch checklist v2"
9 same read after revoke                     200 OK   "Q3 launch checklist v2"

Steps 1–7 एक जैसे हैं। Token-only design में भी step 7 deny होता है, क्योंकि note का project live lookup किया जाता है। Token-only design सिर्फ़ उन्हीं बातों पर पुराना पड़ता है जो token के अंदर रखी हैं। Owner के लिए असली मायने steps 8 और 9 के हैं: उन्होंने project हटाया, फिर connection revoke किया, और chat फिर भी पढ़ती रही। Token-only design में यह token expire होने तक चलता है, जो इस rebuild में expires_in: 3600 है।

Denials दो layers में बंटे हैं। Scope न होना protocol level की failure है: error="insufficient_scope" के साथ 403, और ज़रूरी scope WWW-Authenticate में, ताकि host ज़्यादा scope मांग सके। कौन-सा item शामिल है, उससे जुड़ी हर चीज़ एक सामान्य tool result है जिसमें isError: true होता है। दोबारा authorise करने से वह ठीक नहीं होगा, इसलिए host को retry करने को कहने का कोई मतलब नहीं।

हर call पर check की क़ीमत क्या है?

Server के अंदर access() के चारों ओर time.perf_counter_ns() से मापा गया, हर run में 1,000 calls (500 allowed, 500 denied), एक ऐसे Mac पर जिस पर दूसरे jobs भी चल रहे थे:

	access() median	access() p99	loopback tool call, median
हर call पर check, 6 runs	1.3–1.6 µs	6.1–7.0 µs	0.43–0.78 ms
सिर्फ़ token, 3 runs	0.7–1.6 µs	3.5–7.7 µs	0.35–1.36 ms (2 runs)

Memory में यह recheck loopback HTTP call के noise में खो जाता है। असली server set membership की जगह database lookups करता है, इसलिए उसकी क़ीमत ज़्यादा होती है। यह rebuild उसे माप नहीं सकता, इसलिए उसके लिए कोई number नहीं दिया गया है। अंदाज़े के लिए, Tokyo से live endpoint तक network leg urllib में हर बार नए TLS connection के साथ लगभग 500 ms से 800 ms प्रति request है (हर एक के लिए n=10: initialize median 790 ms, tools/list 816 ms, 401 वाला tools/call 565 ms, हर metadata document लगभग 520–530 ms)। Connector का समय access check में नहीं जाता।

Discovery ख़ुद locally 5 HTTP round trips थी: 401, resource metadata, server metadata, authorize, token। सात runs में इसमें 7.5–13.4 ms लगे, और एक बार Mac busy होने पर 34 ms। Live server के ख़िलाफ़, बिना credentials के किए जा सकने वाले तीन GET/POST legs cold start से मिलाकर लगभग 1.6 s लेते हैं। Authorize leg तो वैसे भी किसी इंसान का इंतज़ार करता है।

Claude osFoundry को call कर सकता है, पर osFoundry आपकी Claude chats क्यों नहीं खोल सकता?

इस setup में caller host है। वही connection खोलता है, tools list करता है और तय करता है कि कब कौन-सा tool call करना है। Server सिर्फ़ जवाब देता है। इस setup में ऐसा कुछ नहीं है जो server को host की conversations तक पहुंच दे। osFoundry का plan यह बात अपनी capability table में कहता है: मनचाही personal ChatGPT/Claude chats खोलना या उनकी list निकालना "No" है, साथ में "No general host API is provided for this"।

इसी से tools का design तय होता है। link_current_chat में chat ख़ुद अपने अंदर से link बनाती है। उसका label chat ख़ुद बताती है, और osFoundry उसे routing के लिए इस्तेमाल करता है, identity के तौर पर नहीं। किसी linked Claude chat को दिया गया काम तब तक इंतज़ार करता है जब तक user वह chat खोलकर उससे check करने को न कहे। ChatGPT में subscribed chats के लिए MCP Events हैं, और osFoundry का plan इसे host-specific मानता है।

Data से जुड़े सारे फ़ैसले server side के पास हैं, क्योंकि सिर्फ़ उसे ही किसी project की मौजूदा स्थिति पता होती है। कब action लेना है और user से पूछना है या नहीं, ये सारे फ़ैसले host side के पास हैं। हर call पर होने वाला check ही server को सही बनाए रखता है जब ये दोनों sides एक-दूसरे से अलग हो जाती हैं।

अगर आप इसे ख़ुद wire up करें

401 के WWW-Authenticate में resource_metadata डालिए और RFC 9728 को /.well-known/oauth-protected-resource/<resource path> पर serve कीजिए। जो client URL हाथ से बनाता है, वह गलती कर सकता है। Header हर client को इससे बचा लेता है।
Sign-in से पहले क्या public है, यह तय कीजिए। osFoundry initialize और tools/list खुला रखता है और tools/call को guard करता है। अगर आपके tool descriptions tenants के बारे में कुछ भी leak करते हैं, तो tools/list को भी guard कीजिए।
हर tool के लिए एक scope और readOnlyHint declare कीजिए। Hosts इनसे approval prompts बना सकते हैं, और 403 insufficient_scope host को दोबारा मांगने के लिए कुछ ठोस देता है।
Token छोटा रखिए: कौन, कौन-सा connection, कौन-से scopes। Workspace, project membership, resource का project और approve करने वाले का मौजूदा role हर call पर दोबारा पढ़िए, ताकि revoke और "दूसरे project में move करना" अगली ही call पर असर करें।
Resource denials को 401/403 की बजाय tool results के रूप में लौटाइए। दूसरा token "यह Note project B में है" को ठीक नहीं करेगा।
Writes के साथ expected_version और एक idempotency key भेजिए। Hosts retry करते हैं, और models calls दोबारा भेजते हैं।

Spec का MCP वाला हिस्सा MCP authorization page पर है। osFoundry की अपनी छोटी परिभाषा उसकी MCP वाली glossary entry में है।

DEV Community: BBT हिन्दी

osFoundry की MCP tool list Codex में कितने token खाती है, और इसे हर project के लिए कैसे छोटा करें?

पहले turn से पहले Codex क्या fetch करता है?

59 tools कितने token के होते हैं?

Codex enabled_tools को कहाँ apply करता है?

Client side को दोबारा बनाना

Handshake में कितना समय लगता है?

Annotations से आपको क्या मिलता है?

असली filter कौन-सा है?

अगर आप इसे ख़ुद wire up करें

Custom connector से Claude chat को अपने osFoundry projects से कैसे जोड़ें

कौन क्या करता है

Setup

1. osFoundry में connection बनाएँ

2. इसे Claude में custom connector के रूप में जोड़ें

3. एक workspace approve करें

4. इसे किसी project में जोड़ें

5. Chat में इसे on करें

एक असली run

सीमा कहाँ है

आगे क्या

Claude का custom connector osFoundry का OAuth server कैसे ढूंढता है, और हर call पर access क्यों check होता है?

Token मिलने से पहले client को क्या दिखता है?

401 उसे कहां भेजता है?

Authorization server अपने बारे में क्या बताता है?

सिर्फ़ scope काफ़ी क्यों नहीं है?

Rebuild

हर call पर check की क़ीमत क्या है?

Claude osFoundry को call कर सकता है, पर osFoundry आपकी Claude chats क्यों नहीं खोल सकता?

अगर आप इसे ख़ुद wire up करें

Codex `enabled_tools` को कहाँ apply करता है?