Skip to content

Commit b97ffb4

Browse files
teallarsoncursoragent
teallarson
and
cursoragent
committed
Make gateway setup guidance explicit and tighten auth input handling.
Replace vague "minimum tools" wording with exact required tool names across docs, doctor scripts, and UI/API errors so users can configure high-signal gateways consistently. Co-authored-by: Cursor <cursoragent@cursor.com>
1 parent 87540d7 commit b97ffb4

File tree

13 files changed

+109
-43
lines changed

13 files changed

+109
-43
lines changed

‎README.md‎

Lines changed: 12 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -28,9 +28,10 @@ An MCP Gateway is a managed tool endpoint in Arcade that your agent connects to
2828
Benefits:
2929

3030
- **One connection point** -- use one `ARCADE_GATEWAY_URL` instead of wiring many tool servers
31+
- **Managed auth** -- Arcade manages user verification, tool OAuth, and handling secrets
3132
- **Tool curation** -- choose exactly which tools your agent can see
3233
- **Faster iteration** -- update tool access in Arcade without changing integration code
33-
- **Cleaner model context** -- smaller, focused toolsets improve tool selection reliability
34+
- **Clean model context** -- smaller, focused toolsets improve tool selection reliability
3435
- **Portable setup** -- same gateway pattern works across frameworks and MCP clients
3536

3637
## Usage
@@ -129,15 +130,16 @@ cp .env.example .env
129130

130131
### Arcade Gateway setup
131132

132-
Add these toolkits to your Arcade Gateway to enable the default triage agent:
133+
For best agent performance, create a dedicated gateway for this starter and keep tool access narrow.
133134

134-
- Slack
135-
- Google Calendar
136-
- Linear
137-
- GitHub
138-
- Gmail
139-
140-
Configure toolkits at [app.arcade.dev/mcp-gateways](https://app.arcade.dev/mcp-gateways).
135+
1. Create a gateway at [app.arcade.dev/mcp-gateways](https://app.arcade.dev/mcp-gateways).
136+
2. Add only these minimum tools (exact names):
137+
- Slack: `Slack_ListConversations`, `Slack_GetMessages`, `Slack_GetConversationMetadata`, `Slack_WhoAmI`
138+
- Google Calendar: `GoogleCalendar_ListEvents`, `GoogleCalendar_ListCalendars`, `GoogleCalendar_WhoAmI`
139+
- Linear: `Linear_GetNotifications`, `Linear_GetRecentActivity`, `Linear_ListIssues`, `Linear_GetIssue`, `Linear_ListProjects`, `Linear_GetProject`, `Linear_WhoAmI`
140+
- GitHub: `Github_ListNotifications`, `Github_GetNotificationSummary`, `Github_ListPullRequests`, `Github_GetPullRequest`, `Github_GetUserOpenItems`, `Github_GetUserRecentActivity`, `Github_GetReviewWorkload`, `Github_GetIssue`, `Github_WhoAmI`
141+
- Gmail: `Gmail_ListEmails`, `Gmail_ListThreads`, `Gmail_GetThread`, `Gmail_SearchThreads`, `Gmail_WhoAmI`
142+
3. Avoid enabling broad "all tools" access. Start small and add tools only when the agent needs them.
141143

142144
## Running the generated project
143145

@@ -181,7 +183,7 @@ Make sure you are running Node.js >= 18. Check with `node --version`.
181183
If the app says `ARCADE_GATEWAY_URL is missing`:
182184

183185
1. Create a gateway at [app.arcade.dev/mcp-gateways](https://app.arcade.dev/mcp-gateways)
184-
2. Add these toolkits: Slack, Google Calendar, Linear, GitHub, Gmail
186+
2. Add the exact minimum tools listed in the **Arcade Gateway setup** section above
185187
3. Copy the gateway URL into `.env` as `ARCADE_GATEWAY_URL`
186188
4. Retry connection in the app
187189

‎templates/_shared/nextjs-ui/app/api/auth/login/route.ts‎

Lines changed: 0 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,6 @@ import { db } from "@/lib/db";
44
import { users } from "@/lib/db/schema";
55
import { verifyPassword, createSession } from "@/lib/auth";
66

7-
const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
8-
97
export async function POST(request: Request) {
108
let body: unknown;
119
try {
@@ -23,9 +21,6 @@ export async function POST(request: Request) {
2321
if (!email || !password) {
2422
return NextResponse.json({ error: "Email and password are required" }, { status: 400 });
2523
}
26-
if (!EMAIL_REGEX.test(email)) {
27-
return NextResponse.json({ error: "Invalid email address" }, { status: 400 });
28-
}
2924

3025
const user = await db.query.users.findFirst({
3126
where: eq(users.email, email),

‎templates/_shared/nextjs-ui/app/api/auth/register/route.ts‎

Lines changed: 0 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,6 @@ import { db } from "@/lib/db";
44
import { users } from "@/lib/db/schema";
55
import { hashPassword, createSession } from "@/lib/auth";
66

7-
const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
8-
97
export async function POST(request: Request) {
108
let body: unknown;
119
try {
@@ -23,9 +21,6 @@ export async function POST(request: Request) {
2321
if (!email || !password) {
2422
return NextResponse.json({ error: "Email and password are required" }, { status: 400 });
2523
}
26-
if (!EMAIL_REGEX.test(email)) {
27-
return NextResponse.json({ error: "Invalid email address" }, { status: 400 });
28-
}
2924
if (password.length < 8) {
3025
return NextResponse.json({ error: "Password must be at least 8 characters" }, { status: 400 });
3126
}

‎templates/_shared/nextjs-ui/app/dashboard/page.tsx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -128,7 +128,7 @@ function DashboardContent() {
128128
auth_incomplete: "Authorization was not completed. Please try connecting again.",
129129
auth_failed: "Authorization failed. Please try again.",
130130
gateway_missing:
131-
"ARCADE_GATEWAY_URL is missing. Create one at https://app.arcade.dev/mcp-gateways, add Slack, Google Calendar, Linear, GitHub, and Gmail, then set ARCADE_GATEWAY_URL in .env.",
131+
"ARCADE_GATEWAY_URL is missing. Create one at https://app.arcade.dev/mcp-gateways, add only the minimum required tools from Slack, Google Calendar, Linear, GitHub, and Gmail, then set ARCADE_GATEWAY_URL in .env.",
132132
verify_failed: "User verification failed. Please try again.",
133133
};
134134
setError(messages[urlError] || `Authentication error: ${urlError}`);

‎templates/_shared/nextjs-ui/scripts/doctor.mjs‎

Lines changed: 36 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,36 @@ import { resolve } from "node:path";
33

44
const ENV_PATH = resolve(process.cwd(), ".env");
55
const REQUIRED_TOOLKITS = ["Slack", "Google Calendar", "Linear", "GitHub", "Gmail"];
6+
const REQUIRED_TOOLS = [
7+
"Slack_ListConversations",
8+
"Slack_GetMessages",
9+
"Slack_GetConversationMetadata",
10+
"Slack_WhoAmI",
11+
"GoogleCalendar_ListEvents",
12+
"GoogleCalendar_ListCalendars",
13+
"GoogleCalendar_WhoAmI",
14+
"Linear_GetNotifications",
15+
"Linear_GetRecentActivity",
16+
"Linear_ListIssues",
17+
"Linear_GetIssue",
18+
"Linear_ListProjects",
19+
"Linear_GetProject",
20+
"Linear_WhoAmI",
21+
"Github_ListNotifications",
22+
"Github_GetNotificationSummary",
23+
"Github_ListPullRequests",
24+
"Github_GetPullRequest",
25+
"Github_GetUserOpenItems",
26+
"Github_GetUserRecentActivity",
27+
"Github_GetReviewWorkload",
28+
"Github_GetIssue",
29+
"Github_WhoAmI",
30+
"Gmail_ListEmails",
31+
"Gmail_ListThreads",
32+
"Gmail_GetThread",
33+
"Gmail_SearchThreads",
34+
"Gmail_WhoAmI",
35+
];
636

737
function parseEnvFile(path) {
838
if (!existsSync(path)) return {};
@@ -62,14 +92,18 @@ async function main() {
6292
if (errors.length > 0) {
6393
console.error("\nDoctor found setup issues:\n");
6494
for (const err of errors) console.error(`- ${err}`);
65-
console.error("\nRecommended toolkits in your Arcade gateway:");
95+
console.error("\nRecommended minimum toolkits (enable only needed tools):");
6696
for (const toolkit of REQUIRED_TOOLKITS) console.error(`- ${toolkit}`);
97+
console.error("\nRecommended minimum tools (exact names):");
98+
for (const tool of REQUIRED_TOOLS) console.error(`- ${tool}`);
6799
process.exit(1);
68100
}
69101

70102
console.log("Doctor check passed.");
71-
console.log("Recommended toolkits in your Arcade gateway:");
103+
console.log("Recommended minimum toolkits (enable only needed tools):");
72104
for (const toolkit of REQUIRED_TOOLKITS) console.log(`- ${toolkit}`);
105+
console.log("Recommended minimum tools (exact names):");
106+
for (const tool of REQUIRED_TOOLS) console.log(`- ${tool}`);
73107
}
74108

75109
main().catch((err) => {

‎templates/_shared/partials/gateway-setup.md.hbs‎

Lines changed: 9 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,14 @@
11
## Arcade Gateway Setup Checklist
22

33
1. Create a gateway at [app.arcade.dev/mcp-gateways](https://app.arcade.dev/mcp-gateways).
4-
2. Add these toolkits to match this starter:
5-
- Slack
6-
- Google Calendar
7-
- Linear
8-
- GitHub
9-
- Gmail
10-
3. Copy the gateway URL into `.env` as `ARCADE_GATEWAY_URL`.
11-
4. Retry the connection check in the app.
4+
2. Add only these minimum tools (exact names):
5+
- Slack: `Slack_ListConversations`, `Slack_GetMessages`, `Slack_GetConversationMetadata`, `Slack_WhoAmI`
6+
- Google Calendar: `GoogleCalendar_ListEvents`, `GoogleCalendar_ListCalendars`, `GoogleCalendar_WhoAmI`
7+
- Linear: `Linear_GetNotifications`, `Linear_GetRecentActivity`, `Linear_ListIssues`, `Linear_GetIssue`, `Linear_ListProjects`, `Linear_GetProject`, `Linear_WhoAmI`
8+
- GitHub: `Github_ListNotifications`, `Github_GetNotificationSummary`, `Github_ListPullRequests`, `Github_GetPullRequest`, `Github_GetUserOpenItems`, `Github_GetUserRecentActivity`, `Github_GetReviewWorkload`, `Github_GetIssue`, `Github_WhoAmI`
9+
- Gmail: `Gmail_ListEmails`, `Gmail_ListThreads`, `Gmail_GetThread`, `Gmail_SearchThreads`, `Gmail_WhoAmI`
10+
3. Avoid broad "all tools" access. Smaller toolsets improve tool selection quality.
11+
4. Copy the gateway URL into `.env` as `ARCADE_GATEWAY_URL`.
12+
5. Retry the connection check in the app.
1213

1314
If you see `ARCADE_GATEWAY_URL is missing`, your app cannot connect to Arcade until this value is set.

‎templates/ai-sdk/app/api/auth/arcade/connect/route.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ export async function POST() {
1818
{
1919
connected: false,
2020
error:
21-
"ARCADE_GATEWAY_URL is missing. Create one at https://app.arcade.dev/mcp-gateways, add Slack, Google Calendar, Linear, GitHub, and Gmail, then set ARCADE_GATEWAY_URL in .env.",
21+
"ARCADE_GATEWAY_URL is missing. Create one at https://app.arcade.dev/mcp-gateways, add only the minimum required tools from Slack, Google Calendar, Linear, GitHub, and Gmail, then set ARCADE_GATEWAY_URL in .env.",
2222
},
2323
{ status: 400 }
2424
);

‎templates/ai-sdk/lib/arcade.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ function getGatewayUrl(): string {
2222
const value = process.env.ARCADE_GATEWAY_URL?.trim();
2323
if (!value) {
2424
throw new Error(
25-
"ARCADE_GATEWAY_URL is missing. Create one at https://app.arcade.dev/mcp-gateways, add Slack, Google Calendar, Linear, GitHub, and Gmail, then set ARCADE_GATEWAY_URL in .env."
25+
"ARCADE_GATEWAY_URL is missing. Create one at https://app.arcade.dev/mcp-gateways, add only the minimum required tools from Slack, Google Calendar, Linear, GitHub, and Gmail, then set ARCADE_GATEWAY_URL in .env."
2626
);
2727
}
2828
return value;

‎templates/langchain/app/doctor.py‎

Lines changed: 38 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,36 @@
1414
from app.config import settings
1515

1616
RECOMMENDED_TOOLKITS = ["Slack", "Google Calendar", "Linear", "GitHub", "Gmail"]
17+
RECOMMENDED_TOOLS = [
18+
"Slack_ListConversations",
19+
"Slack_GetMessages",
20+
"Slack_GetConversationMetadata",
21+
"Slack_WhoAmI",
22+
"GoogleCalendar_ListEvents",
23+
"GoogleCalendar_ListCalendars",
24+
"GoogleCalendar_WhoAmI",
25+
"Linear_GetNotifications",
26+
"Linear_GetRecentActivity",
27+
"Linear_ListIssues",
28+
"Linear_GetIssue",
29+
"Linear_ListProjects",
30+
"Linear_GetProject",
31+
"Linear_WhoAmI",
32+
"Github_ListNotifications",
33+
"Github_GetNotificationSummary",
34+
"Github_ListPullRequests",
35+
"Github_GetPullRequest",
36+
"Github_GetUserOpenItems",
37+
"Github_GetUserRecentActivity",
38+
"Github_GetReviewWorkload",
39+
"Github_GetIssue",
40+
"Github_WhoAmI",
41+
"Gmail_ListEmails",
42+
"Gmail_ListThreads",
43+
"Gmail_GetThread",
44+
"Gmail_SearchThreads",
45+
"Gmail_WhoAmI",
46+
]
1747

1848

1949
async def _gateway_reachable(url: str) -> bool:
@@ -45,15 +75,21 @@ async def main() -> int:
4575
print("\nDoctor found setup issues:\n")
4676
for err in errors:
4777
print(f"- {err}")
48-
print("\nRecommended toolkits in your Arcade gateway:")
78+
print("\nRecommended minimum toolkits (enable only needed tools):")
4979
for toolkit in RECOMMENDED_TOOLKITS:
5080
print(f"- {toolkit}")
81+
print("\nRecommended minimum tools (exact names):")
82+
for tool in RECOMMENDED_TOOLS:
83+
print(f"- {tool}")
5184
return 1
5285

5386
print("Doctor check passed.")
54-
print("Recommended toolkits in your Arcade gateway:")
87+
print("Recommended minimum toolkits (enable only needed tools):")
5588
for toolkit in RECOMMENDED_TOOLKITS:
5689
print(f"- {toolkit}")
90+
print("Recommended minimum tools (exact names):")
91+
for tool in RECOMMENDED_TOOLS:
92+
print(f"- {tool}")
5793
return 0
5894

5995

‎templates/langchain/app/routes/arcade.py‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -46,8 +46,9 @@ async def connect(request: Request, db: AsyncSession = Depends(get_db)):
4646
"connected": False,
4747
"error": (
4848
"ARCADE_GATEWAY_URL is missing. Create one at "
49-
"https://app.arcade.dev/mcp-gateways, add Slack, Google Calendar, "
50-
"Linear, GitHub, and Gmail, then set ARCADE_GATEWAY_URL in .env."
49+
"https://app.arcade.dev/mcp-gateways, add only the minimum required "
50+
"tools from Slack, Google Calendar, Linear, GitHub, and Gmail, then "
51+
"set ARCADE_GATEWAY_URL in .env."
5152
),
5253
},
5354
status_code=400,
@@ -128,8 +129,9 @@ async def check_sources(request: Request, db: AsyncSession = Depends(get_db)):
128129
{
129130
"error": (
130131
"ARCADE_GATEWAY_URL is missing. Create one at "
131-
"https://app.arcade.dev/mcp-gateways, add Slack, Google Calendar, "
132-
"Linear, GitHub, and Gmail, then set ARCADE_GATEWAY_URL in .env."
132+
"https://app.arcade.dev/mcp-gateways, add only the minimum required "
133+
"tools from Slack, Google Calendar, Linear, GitHub, and Gmail, then "
134+
"set ARCADE_GATEWAY_URL in .env."
133135
),
134136
"sources": {},
135137
},

0 commit comments

Comments
 (0)