Skip to content

Commit 68aa6c5

Browse files
devin-ai-integration[bot]kenny@buildwithfern.com
devin-ai-integration[bot]
and
[email protected]
committed
feat: add Fern API definition for MCP endpoints
- Create fern/apis/fern-docs-mcp/openapi.json with OpenAPI 3.1.0 spec - Add generators.yml to properly configure the API definition - Update MCP server documentation to reference the API spec location - Includes both get-jwt and search/v2/key endpoints with full specifications Co-Authored-By: [email protected] <[email protected]>
1 parent b3c5a85 commit 68aa6c5

File tree

3 files changed

+235
-1
lines changed

3 files changed

+235
-1
lines changed

‎fern/apis/fern-docs-mcp/generators.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
api:
2+
specs:
3+
- openapi: openapi.json

‎fern/apis/fern-docs-mcp/openapi.json‎

Lines changed: 231 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,231 @@
1+
{
2+
"openapi": "3.1.0",
3+
"info": {
4+
"title": "Fern Docs MCP API",
5+
"version": "1.0.0",
6+
"description": "API endpoints for MCP agents to authenticate and search Fern documentation sites."
7+
},
8+
"servers": [
9+
{
10+
"url": "https://docs.example.com",
11+
"description": "Your documentation domain"
12+
}
13+
],
14+
"paths": {
15+
"/api/fern-docs/get-jwt": {
16+
"get": {
17+
"summary": "Exchange an API key for a JWT",
18+
"description": "Exchange a Fern API key for a JWT token that can be used to access protected documentation endpoints.",
19+
"operationId": "getJwt",
20+
"parameters": [
21+
{
22+
"name": "FERN_API_KEY",
23+
"in": "header",
24+
"required": true,
25+
"schema": {
26+
"type": "string"
27+
},
28+
"description": "Your Fern API key"
29+
},
30+
{
31+
"name": "ROLES",
32+
"in": "header",
33+
"required": false,
34+
"schema": {
35+
"type": "string"
36+
},
37+
"description": "Comma-separated list of roles (e.g., \"botanist,seedling\")"
38+
},
39+
{
40+
"name": "x-fern-host",
41+
"in": "header",
42+
"required": false,
43+
"schema": {
44+
"type": "string"
45+
},
46+
"description": "Documentation domain (required on preview URLs)"
47+
}
48+
],
49+
"responses": {
50+
"200": {
51+
"description": "Successfully generated JWT",
52+
"content": {
53+
"application/json": {
54+
"schema": {
55+
"type": "object",
56+
"properties": {
57+
"fern_token": {
58+
"type": "string",
59+
"description": "JWT token for authenticating subsequent requests"
60+
},
61+
"roles": {
62+
"type": "array",
63+
"items": {
64+
"type": "string"
65+
},
66+
"description": "Roles included in the JWT"
67+
}
68+
},
69+
"required": ["fern_token", "roles"]
70+
}
71+
}
72+
}
73+
},
74+
"400": {
75+
"description": "Bad request (local preview, self-hosted, or SSO environment)",
76+
"content": {
77+
"application/json": {
78+
"schema": {
79+
"type": "object",
80+
"properties": {
81+
"error": {
82+
"type": "string"
83+
}
84+
}
85+
}
86+
}
87+
}
88+
},
89+
"401": {
90+
"description": "Unauthorized (missing or invalid API key)",
91+
"content": {
92+
"application/json": {
93+
"schema": {
94+
"type": "object",
95+
"properties": {
96+
"error": {
97+
"type": "string"
98+
}
99+
}
100+
}
101+
}
102+
}
103+
},
104+
"403": {
105+
"description": "Forbidden (API key does not belong to organization)",
106+
"content": {
107+
"application/json": {
108+
"schema": {
109+
"type": "object",
110+
"properties": {
111+
"error": {
112+
"type": "string"
113+
}
114+
}
115+
}
116+
}
117+
}
118+
},
119+
"500": {
120+
"description": "Internal server error",
121+
"content": {
122+
"application/json": {
123+
"schema": {
124+
"type": "object",
125+
"properties": {
126+
"error": {
127+
"type": "string"
128+
}
129+
}
130+
}
131+
}
132+
}
133+
}
134+
}
135+
}
136+
},
137+
"/api/fern-docs/search/v2/key": {
138+
"get": {
139+
"summary": "Get search credentials",
140+
"description": "Retrieve Algolia search credentials for querying documentation. Supports API key or JWT authentication.",
141+
"operationId": "getSearchKey",
142+
"parameters": [
143+
{
144+
"name": "FERN_API_KEY",
145+
"in": "header",
146+
"required": false,
147+
"schema": {
148+
"type": "string"
149+
},
150+
"description": "Your Fern API key (Option 1)"
151+
},
152+
{
153+
"name": "FERN_TOKEN",
154+
"in": "header",
155+
"required": false,
156+
"schema": {
157+
"type": "string"
158+
},
159+
"description": "JWT token from /api/fern-docs/get-jwt (Option 2)"
160+
},
161+
{
162+
"name": "ROLES",
163+
"in": "header",
164+
"required": false,
165+
"schema": {
166+
"type": "string"
167+
},
168+
"description": "Comma-separated list of roles (only with FERN_API_KEY)"
169+
},
170+
{
171+
"name": "X-User-Token",
172+
"in": "header",
173+
"required": false,
174+
"schema": {
175+
"type": "string"
176+
},
177+
"description": "Optional user identifier for analytics"
178+
},
179+
{
180+
"name": "x-fern-host",
181+
"in": "header",
182+
"required": false,
183+
"schema": {
184+
"type": "string"
185+
},
186+
"description": "Documentation domain (required on preview URLs)"
187+
}
188+
],
189+
"responses": {
190+
"200": {
191+
"description": "Successfully retrieved search credentials",
192+
"content": {
193+
"application/json": {
194+
"schema": {
195+
"type": "object",
196+
"properties": {
197+
"appId": {
198+
"type": "string",
199+
"description": "Algolia application ID"
200+
},
201+
"apiKey": {
202+
"type": "string",
203+
"description": "Short-lived Algolia search API key"
204+
},
205+
"roles": {
206+
"type": "array",
207+
"items": {
208+
"type": "string"
209+
},
210+
"description": "Roles included in the search key (only with FERN_API_KEY auth)"
211+
}
212+
},
213+
"required": ["appId", "apiKey"]
214+
}
215+
}
216+
}
217+
},
218+
"400": {
219+
"description": "Bad request (local preview or unsupported preview URL)"
220+
},
221+
"401": {
222+
"description": "Unauthorized (invalid API key)"
223+
},
224+
"403": {
225+
"description": "Forbidden (API key does not belong to organization)"
226+
}
227+
}
228+
}
229+
}
230+
}
231+
}

‎fern/products/ask-fern/pages/features/mcp-server.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -170,7 +170,7 @@ curl -X GET https://docs.example.com/api/fern-docs/search/v2/key \
170170

171171
## OpenAPI specification
172172

173-
The complete OpenAPI specification for these endpoints:
173+
The complete OpenAPI specification for these endpoints is available in the repository at `fern/apis/fern-docs-mcp/openapi.json`.
174174

175175
```yaml
176176
openapi: 3.1.0

0 commit comments

Comments
 (0)