Skip to content

Commit 128ad49

Browse files
ryanpl-kintsugiryanpl-kintsugi
committed
add multiple MCP generations
1 parent 9bc7c98 commit 128ad49

8 files changed

Lines changed: 51447 additions & 29 deletions

‎.github/workflows/update-api-docs.yml‎

Lines changed: 37 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,8 @@ on:
1515
- 'scripts/generate-api-docs.sh'
1616
- 'scripts/add-mcp-config.sh'
1717
- 'scripts/add-mcp-config-to-endpoints.sh'
18+
- 'scripts/extract-public-partners-endpoints.py'
19+
- 'scripts/setup-mcp-servers.sh'
1820

1921
jobs:
2022
update-api-docs:
@@ -48,23 +50,38 @@ jobs:
4850
4951
echo "✅ OpenAPI specs downloaded successfully!"
5052
51-
- name: Add MCP configuration to Partners API
53+
- name: Setup MCP servers
5254
run: |
53-
echo "🔧 Adding MCP configuration to Partners API spec..."
55+
echo "🔧 Setting up MCP servers..."
5456
5557
# Install jq if not available
5658
if ! command -v jq &> /dev/null; then
5759
echo "📦 Installing jq..."
5860
sudo apt-get update && sudo apt-get install -y jq
5961
fi
6062
61-
# Make script executable
63+
# Make scripts executable
6264
chmod +x scripts/add-mcp-config-to-endpoints.sh
65+
chmod +x scripts/extract-public-partners-endpoints.py
66+
chmod +x scripts/setup-mcp-servers.sh
6367
64-
# Add MCP configuration to root and all endpoints explicitly
68+
# Download Customer API and add MCP config (mcp-public)
69+
echo "📥 Downloading Customer API spec..."
70+
curl -s https://api-doc.trykintsugi.com/openapi.json -o openapi.json
71+
./scripts/add-mcp-config-to-endpoints.sh openapi.json
72+
73+
# Ensure Partners API has MCP config (mcp-internal)
74+
echo "🔧 Configuring Partners API (internal)..."
6575
./scripts/add-mcp-config-to-endpoints.sh openapi-partners.json
6676
67-
echo "✅ MCP configuration added! All Partners API endpoints are now explicitly enabled as MCP tools"
77+
# Create filtered Partners API spec (mcp-partners)
78+
echo "🔧 Creating filtered Partners API spec (public)..."
79+
python3 scripts/extract-public-partners-endpoints.py
80+
81+
echo "✅ MCP servers configured!"
82+
echo " - /mcp-public: Customer API"
83+
echo " - /mcp-partners: Public Partners API endpoints"
84+
echo " - /mcp-internal: All Partners API endpoints"
6885
6986
- name: Validate OpenAPI specs
7087
run: |
@@ -81,6 +98,17 @@ jobs:
8198
exit 1
8299
fi
83100
101+
if [ ! -s openapi-partners-public.json ]; then
102+
echo "❌ Partners API public spec is empty or missing"
103+
exit 1
104+
fi
105+
106+
# Verify MCP configuration
107+
echo "🔍 Verifying MCP configuration..."
108+
jq -e '."x-mint".mcp.enabled == true' openapi.json > /dev/null && echo "✅ Customer API has MCP enabled" || echo "❌ Customer API missing MCP config"
109+
jq -e '."x-mint".mcp.enabled == true' openapi-partners.json > /dev/null && echo "✅ Partners API (internal) has MCP enabled" || echo "❌ Partners API (internal) missing MCP config"
110+
jq -e '."x-mint".mcp.enabled == true' openapi-partners-public.json > /dev/null && echo "✅ Partners API (public) has MCP enabled" || echo "❌ Partners API (public) missing MCP config"
111+
84112
echo "✅ OpenAPI specs are valid!"
85113
86114
- name: Generate API documentation
@@ -114,11 +142,12 @@ jobs:
114142
git config user.email "actions@github.com"
115143
116144
# Add all changes (OpenAPI files + generated docs)
117-
git add openapi.json openapi-partners.json reference/api/ reference/partners/
145+
git add openapi.json openapi-partners.json openapi-partners-public.json reference/api/ reference/partners/
118146
git commit -m "🤖 Auto-update API documentation and OpenAPI specs [skip ci]
119147
120-
- Updated openapi.json from https://api-doc.trykintsugi.com/openapi.json
121-
- Updated openapi-partners.json from https://api.trykintsugi.com/openapi.json
148+
- Updated openapi.json from https://api-doc.trykintsugi.com/openapi.json (→ /mcp-public)
149+
- Updated openapi-partners.json from https://api.trykintsugi.com/openapi.json (→ /mcp-internal)
150+
- Generated openapi-partners-public.json with public endpoints only (→ /mcp-partners)
122151
- Regenerated API reference documentation
123152
- Generated on: $(date)"
124153
git push

‎MCP_MULTIPLE_SERVERS.md‎

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
# Multiple MCP Servers Setup
2+
3+
This document explains how we've configured three separate MCP servers for different audiences.
4+
5+
## Overview
6+
7+
We now have **three MCP servers** serving different API endpoint sets:
8+
9+
1. **`/mcp-public`** - Customer API endpoints (publicly available)
10+
2. **`/mcp-partners`** - Public Partners API endpoints (only those listed in "API Reference - Partners")
11+
3. **`/mcp-internal`** - All Partners API endpoints (internal/full spec)
12+
13+
## MCP Server Details
14+
15+
### `/mcp-public`
16+
- **Source**: `openapi.json` (Customer API)
17+
- **URL**: `https://api-doc.trykintsugi.com/openapi.json`
18+
- **Endpoints**: ~28 Customer API endpoints
19+
- **Audience**: Public users
20+
- **Configuration**: Auto-downloaded and MCP-enabled in workflow
21+
22+
### `/mcp-partners`
23+
- **Source**: `openapi-partners-public.json` (filtered Partners API)
24+
- **Filtering**: Only endpoints listed in "API Reference - Partners" section of `docs.json`
25+
- **Endpoints**: ~51 public Partners API endpoints (72 pages → 51 unique paths)
26+
- **Audience**: Partners who need public API access
27+
- **Configuration**: Generated by `extract-public-partners-endpoints.py` script
28+
29+
### `/mcp-internal`
30+
- **Source**: `openapi-partners.json` (full Partners API)
31+
- **URL**: `https://api.trykintsugi.com/openapi.json`
32+
- **Endpoints**: ~274 Partners API endpoints (all internal endpoints)
33+
- **Audience**: Internal use, full API access
34+
- **Configuration**: Auto-downloaded and MCP-enabled in workflow
35+
36+
## File Structure
37+
38+
```
39+
docs-v2/
40+
├── openapi.json # Customer API → /mcp-public
41+
├── openapi-partners.json # Full Partners API → /mcp-internal
42+
├── openapi-partners-public.json # Filtered Partners API → /mcp-partners
43+
├── docs.json # Configuration with 3 OpenAPI entries
44+
└── scripts/
45+
├── setup-mcp-servers.sh # Main setup script
46+
├── extract-public-partners-endpoints.py # Filters public endpoints
47+
└── add-mcp-config-to-endpoints.sh # Adds MCP config to endpoints
48+
```
49+
50+
## How It Works
51+
52+
### 1. Public Endpoints Extraction
53+
54+
The `extract-public-partners-endpoints.py` script:
55+
- Reads `docs.json` to find all pages in "API Reference - Partners"
56+
- Parses MDX files to extract OpenAPI paths (e.g., `post /v1/transactions`)
57+
- Filters `openapi-partners.json` to only include those endpoints
58+
- Adds MCP configuration to the filtered spec
59+
60+
### 2. MCP Configuration
61+
62+
Each OpenAPI file has:
63+
- Root-level: `x-mint.mcp.enabled: true`
64+
- Endpoint-level: Each operation has `x-mint.mcp.enabled: true`
65+
66+
### 3. Docs.json Configuration
67+
68+
```json
69+
{
70+
"openapi": [
71+
{
72+
"url": "./openapi.json",
73+
"label": "Customer API",
74+
"mcp": {
75+
"path": "/mcp-public"
76+
}
77+
},
78+
{
79+
"url": "./openapi-partners-public.json",
80+
"label": "Partners API (Public)",
81+
"mcp": {
82+
"path": "/mcp-partners"
83+
}
84+
},
85+
{
86+
"url": "./openapi-partners.json",
87+
"label": "Partners API (Internal)",
88+
"mcp": {
89+
"path": "/mcp-internal"
90+
}
91+
}
92+
]
93+
}
94+
```
95+
96+
## Automatic Updates
97+
98+
The GitHub Actions workflow (`.github/workflows/update-api-docs.yml`) automatically:
99+
1. Downloads Customer API spec → `openapi.json`
100+
2. Downloads Partners API spec → `openapi-partners.json`
101+
3. Adds MCP configuration to both
102+
4. Generates filtered Partners API spec → `openapi-partners-public.json`
103+
5. Commits and deploys all three files
104+
105+
## Manual Setup
106+
107+
To set up locally:
108+
109+
```bash
110+
# Run the setup script
111+
./scripts/setup-mcp-servers.sh
112+
113+
# Or manually:
114+
# 1. Download Customer API
115+
curl https://api-doc.trykintsugi.com/openapi.json -o openapi.json
116+
./scripts/add-mcp-config-to-endpoints.sh openapi.json
117+
118+
# 2. Download Partners API
119+
curl https://api.trykintsugi.com/openapi.json -o openapi-partners.json
120+
./scripts/add-mcp-config-to-endpoints.sh openapi-partners.json
121+
122+
# 3. Generate filtered Partners API
123+
python3 scripts/extract-public-partners-endpoints.py
124+
```
125+
126+
## Accessing MCP Servers
127+
128+
Once deployed, the MCP servers **should** be available at:
129+
- `https://kintsugi.mintlify.app/mcp-public` (Customer API)
130+
- `https://kintsugi.mintlify.app/mcp-partners` (Public Partners API)
131+
- `https://kintsugi.mintlify.app/mcp-internal` (Internal Partners API)
132+
133+
**Important Note**: Mintlify may not support custom `mcp.path` configuration in `docs.json`. If the custom paths don't work, Mintlify will likely generate MCP servers at:
134+
- `/mcp` (first OpenAPI file - Customer API)
135+
- `/mcp-1` (second OpenAPI file - Partners Public)
136+
- `/mcp-2` (third OpenAPI file - Partners Internal)
137+
138+
**To verify actual paths**:
139+
1. Check Mintlify dashboard → Products → MCP Server
140+
2. Look for all available MCP servers and their paths
141+
3. Update this documentation with the actual paths if different
142+
143+
**If custom paths are needed**, you may need to:
144+
- Contact Mintlify support to request custom MCP server path support
145+
- Or reorganize the OpenAPI files in `docs.json` to match desired order
146+
147+
## Troubleshooting
148+
149+
### MCP Servers Not Showing
150+
151+
1. **Check deployment**: Ensure all three OpenAPI files are committed
152+
2. **Verify MCP config**: Check that each file has `x-mint.mcp.enabled: true`
153+
3. **Manual update**: Trigger manual update in Mintlify dashboard
154+
4. **Check paths**: Verify actual MCP server paths in Mintlify dashboard
155+
156+
### Public Endpoints Missing
157+
158+
If `/mcp-partners` is missing endpoints:
159+
1. Check `docs.json` - ensure endpoint is listed in "API Reference - Partners"
160+
2. Verify MDX file exists: `reference/partners/{category}/{endpoint}.mdx`
161+
3. Check MDX frontmatter: Should have `openapi: {method} {path}`
162+
4. Re-run `extract-public-partners-endpoints.py`
163+
164+
## References
165+
166+
- [Mintlify MCP Documentation](https://www.mintlify.com/docs/ai/model-context-protocol)
167+
- Customer API: https://api-doc.trykintsugi.com/openapi.json
168+
- Partners API: https://api.trykintsugi.com/openapi.json
169+

‎docs.json‎

Lines changed: 15 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,11 +5,24 @@
55
"openapi": [
66
{
77
"url": "./openapi.json",
8-
"label": "Customer API"
8+
"label": "Customer API",
9+
"mcp": {
10+
"path": "/mcp-public"
11+
}
12+
},
13+
{
14+
"url": "./openapi-partners-public.json",
15+
"label": "Partners API (Public)",
16+
"mcp": {
17+
"path": "/mcp-partners"
18+
}
919
},
1020
{
1121
"url": "./openapi-partners.json",
12-
"label": "Partners API"
22+
"label": "Partners API (Internal)",
23+
"mcp": {
24+
"path": "/mcp-internal"
25+
}
1326
}
1427
],
1528
"api": {

0 commit comments

Comments
 (0)