feat(api): add v2 endpoints for MCP servers, skills, custom tools, folders, and credentials

[TheodoreSpeaks]

Summary

• Adds full CRUD to the public v2 API for five resources that had no public surface at all: MCP servers, skills, custom tools, folders, credentials (25 endpoints). Provisioning a workspace by API no longer has to stop and use the UI.
• Secret material is write-only on read. MCP request headers return as hasHeaders + headerNames (never values); credential secrets return as hasServiceAccountKey. These shapes were built for a browser session — over an API key the old ones were a token-exfiltration primitive.
• MCP create is a real create: 409 on a duplicate URL, checked before the lib's upsert can overwrite the existing server. {{ENV_VAR}} URLs are rejected (they skip the domain allowlist and SSRF resolve, so over a key that's a stored SSRF path), bodies are strict, and url must be an absolute http(s) URL.
• Extracts lib/skills/orchestration/ and lib/credentials/orchestration/credential-create.ts, then repoints the existing session routes and copilot manage_skill at them. Skill field limits used to live only in the route's Zod contract, so copilot bypassed them entirely — now every caller gets the same rules. app/api/credentials/route.ts went 720 → 205 lines.
• Hand-authored apps/docs/openapi-v2-resources.json (5 tags, 25 operations), registered in both SPEC_FILES lists and all 6 locale meta.jsons.

Type of Change

• New feature

Testing

• bun run type-check ✅, check:openapi ✅ (7 specs, 82 operations, 73 contracts cross-checked), check:api-validation ✅ (route baseline 1028 → 1038), lint:check ✅
• 172 new tests across 10 route files; vitest app/api/v2 lib/skills app/api/skills app/api/credentials app/api/folders app/api/tools lib/copilot → 1412 passed
• Exercised live against a local dev server with a real API key and DB: full CRUD round-trip on all five families, plus the departures — header values confirmed absent from responses, duplicate MCP URL → 409 without clobbering, {{ENV}}/file:// → 400, built-in skill name → 400, custom-tool rename collision → 409, folder cascade counts, credential idempotent re-create returning the same id. Auth: no key → 401, bad key → 401, foreign workspace → 403. All test artifacts cleaned up.

Notes for review

• check:api-validation:strict fails on this branch, but not because of this PR. The doubleCasts ratchet reads 9 vs a baseline of 8; all nine live in files this diff never touches (tools/hosting.ts, contracts/tables.ts, executor/utils/errors.ts, packages/logger, packages/ts-sdk) and all are present at the base commit. improvement(external-endpoints): v2 versions with clean signatures + updated docs based on openapi spec #5273's own Lint and Test is already FAILURE for the same reason. I did not bump the baseline — that would hide an existing regression inside an unrelated PR. Happy to bump it if you'd rather have green CI here.
• Judgment calls worth a look: credentials create excludes oauth (needs an internal account.id from the browser flow); create always returns 201 including the idempotent source replay, because the OpenAPI checker only validates the numerically-smallest 2xx; folders require resourceType explicitly rather than defaulting to workflow; the skills list omits content (50k chars each) in favour of the detail endpoint; /api/skills POST is no longer a single transaction — it applies per item so one authority owns the rules.

Checklist

• Code follows project style guidelines
• Self-reviewed my changes
• Tests added/updated and passing
• No new warnings introduced
• I confirm that I have read and agree to the terms outlined in the Contributor License Agreement (CLA)

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
docs	Skipped		Aug 1, 2026 6:43am

[cursor]

PR Summary

High Risk
Large new public API surface over credentials, MCP URLs, and sandboxed custom-tool code, with security-sensitive read masking and secret handling that must stay correct on every path.

Overview
Introduces the Sim API v2 — Workspace Resources surface: full CRUD for MCP servers, skills, custom tools, folders, and credentials under /api/v2, with the usual v2 envelopes, rate limits, and feature-flag gate.

Secrets stay write-only on read — MCP headers surface as hasHeaders / headerNames; credentials use hasServiceAccountKey instead of returning encrypted material. Credential detail/list routes mask inaccessible credentials as 404 so membership cannot be enumerated. MCP create rejects templated {{ENV_VAR}} URLs and duplicate URLs with 409 before an upsert can overwrite.

Session routes are centralized — credential create/list moves into performCreateCredential and listVisibleWorkspaceCredentials; skills POST/DELETE use lib/skills/orchestration so copilot and the UI share the same field limits and editor checks. Provider outage codes map consistently to 503 via isProviderOutageCode. v2 credential create excludes oauth (browser connect flow only); idempotent creates still return 201.

Docs add openapi-v2-resources.json, register it in apps/docs/lib/openapi.ts, and add generated nav entries for all five resource families across locale meta.json files. Rate-limit buckets for the new v2 routes are added in v1 middleware.

^{Reviewed by Cursor Bugbot for commit 2b33a0e. Bugbot is set up for automated code reviews on this repo. Configure here.}

[greptile-apps]

Greptile Summary

The PR adds public v2 CRUD endpoints and OpenAPI documentation for MCP servers, skills, custom tools, folders, and credentials, while extracting shared credential and skill orchestration.

• Adds tenant-scoped API-key routes for five workspace resource families.
• Keeps credential and MCP secret values write-only in API responses.
• Reuses shared lifecycle and authorization logic across public and session-backed routes.
• Registers the new resource specification throughout the localized documentation site.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains; the credential-role issue is fixed, and the folder-lock thread concerned unchanged behavior already reachable through the existing route.

Important Files Changed

Filename	Overview
apps/sim/app/api/v2/credentials/route.ts	Adds credential list/create endpoints and now resolves the actual authorization role for idempotently matched credentials.
apps/sim/lib/credentials/orchestration/credential-create.ts	Centralizes credential creation, idempotent source matching, membership creation, and provider-specific validation.
apps/sim/app/api/v2/folders/[id]/route.ts	Adds workspace-scoped folder read, update, and cascade-delete handlers using the existing lifecycle implementation.
apps/sim/lib/skills/orchestration/skill-lifecycle.ts	Centralizes skill validation and lifecycle behavior so API and copilot callers share the same constraints.
apps/docs/openapi-v2-resources.json	Documents the 25 public resource operations, request contracts, secret-redacted response shapes, and standard API errors.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  Client[API client] --> Auth[API-key and workspace authorization]
  Auth --> V2[Public v2 resource routes]
  V2 --> MCP[MCP servers]
  V2 --> Skills[Skills]
  V2 --> Tools[Custom tools]
  V2 --> Folders[Folders]
  V2 --> Credentials[Credentials]
  Skills --> SkillLifecycle[Shared skill orchestration]
  Credentials --> CredentialLifecycle[Shared credential orchestration]
  MCP --> DB[(Workspace data)]
  SkillLifecycle --> DB
  Tools --> DB
  Folders --> DB
  CredentialLifecycle --> DB
  Specs[OpenAPI resource specification] -. documents .-> V2

Loading

_{Reviews (6): Last reviewed commit: "fix(credentials): use the shared outage ..." | Re-trigger Greptile}

[TheodoreSpeaks]

@greptile

[TheodoreSpeaks]

@cursor review

[TheodoreSpeaks]

@greptile

[TheodoreSpeaks]

@cursor review

[TheodoreSpeaks]

@greptile

[TheodoreSpeaks]

@cursor review

[TheodoreSpeaks]

@greptile

[TheodoreSpeaks]

@cursor review

[TheodoreSpeaks]

@greptile

[TheodoreSpeaks]

@cursor review

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 2b33a0e. Configure here.}