The open-source agent harness - the runtime layer that turns an LLM into a working agent.
chore: add public GET /api/v1/mcp-servers/{name} (#655)
Srajan Asthanaa1af95df3d97
diff --git a/.changeset/public-mcp-get.md b/.changeset/public-mcp-get.mdnew file mode 100644index 000000000..ef2c8c3f3--- /dev/null+++ b/.changeset/public-mcp-get.md@@ -0,0 +1,5 @@+---+"@truefoundry/trueforge": patch+---++Add public GET /api/v1/mcp-servers/{name} returning the chat projection with live per-user auth_status.diff --git a/.github/fern/openapi/openapi.json b/.github/fern/openapi/openapi.jsonindex d363e49a2..924dbb06c 100644--- a/.github/fern/openapi/openapi.json+++ b/.github/fern/openapi/openapi.json@@ -1335,6 +1335,17 @@],"type": "object"},+ "GetAvailableMCPServerResponse": {+ "properties": {+ "data": {+ "$ref": "#/components/schemas/AvailableMCPServer"+ }+ },+ "required": [+ "data"+ ],+ "type": "object"+ },"GetCapabilitiesResponse": {"properties": {"data": {@@ -6094,6 +6105,64 @@"x-fern-ignore": true}},+ "/api/v1/mcp-servers/{name}": {+ "get": {+ "description": "A single MCP server as the slim chat projection, with live per-user auth_status.",+ "parameters": [+ {+ "description": "MCP server name.",+ "in": "path",+ "name": "name",+ "required": true,+ "schema": {+ "description": "MCP server name.",+ "minLength": 1,+ "type": "string"+ }+ }+ ],+ "responses": {+ "200": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/GetAvailableMCPServerResponse"+ }+ }+ },+ "description": "The MCP server (chat projection)."+ },+ "401": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/RequestErrorResponse"+ }+ }+ },+ "description": "OIDC is configured and the request has no valid session cookie."+ },+ "404": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/RequestErrorResponse"+ }+ }+ },+ "description": "MCP server not found."+ }+ },+ "summary": "Get an MCP server for chat",+ "tags": [+ "MCP Servers"+ ],+ "x-fern-sdk-group-name": [+ "mcpServers"+ ],+ "x-fern-sdk-method-name": "get"+ }+ },"/api/v1/mcp-servers/{name}/authorize": {"delete": {"description": "Disconnects OAuth for the MCP server when applicable and returns the updated server with auth_status. No-op when the server does not use stored OAuth tokens.",diff --git a/docs/openapi.json b/docs/openapi.jsonindex d363e49a2..924dbb06c 100644--- a/docs/openapi.json+++ b/docs/openapi.json@@ -1335,6 +1335,17 @@],"type": "object"},+ "GetAvailableMCPServerResponse": {+ "properties": {+ "data": {+ "$ref": "#/components/schemas/AvailableMCPServer"+ }+ },+ "required": [+ "data"+ ],+ "type": "object"+ },"GetCapabilitiesResponse": {"properties": {"data": {@@ -6094,6 +6105,64 @@"x-fern-ignore": true}},+ "/api/v1/mcp-servers/{name}": {+ "get": {+ "description": "A single MCP server as the slim chat projection, with live per-user auth_status.",+ "parameters": [+ {+ "description": "MCP server name.",+ "in": "path",+ "name": "name",+ "required": true,+ "schema": {+ "description": "MCP server name.",+ "minLength": 1,+ "type": "string"+ }+ }+ ],+ "responses": {+ "200": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/GetAvailableMCPServerResponse"+ }+ }+ },+ "description": "The MCP server (chat projection)."+ },+ "401": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/RequestErrorResponse"+ }+ }+ },+ "description": "OIDC is configured and the request has no valid session cookie."+ },+ "404": {+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/RequestErrorResponse"+ }+ }+ },+ "description": "MCP server not found."+ }+ },+ "summary": "Get an MCP server for chat",+ "tags": [+ "MCP Servers"+ ],+ "x-fern-sdk-group-name": [+ "mcpServers"+ ],+ "x-fern-sdk-method-name": "get"+ }+ },"/api/v1/mcp-servers/{name}/authorize": {"delete": {"description": "Disconnects OAuth for the MCP server when applicable and returns the updated server with auth_status. No-op when the server does not use stored OAuth tokens.",diff --git a/packages/trueforge-sdk/reference.md b/packages/trueforge-sdk/reference.mdindex 9eaf05a3b..a0daae46c 100644--- a/packages/trueforge-sdk/reference.md+++ b/packages/trueforge-sdk/reference.md@@ -500,6 +500,69 @@ await client.mcpServers.list();</dl>+</dd>+</dl>+</details>++<details><summary><code>client.mcpServers.<a href="/src/api/resources/mcpServers/client/Client.ts">get</a>(name) -> TrueForge.GetAvailableMcpServerResponse</code></summary>+<dl>+<dd>++#### π Description++<dl>+<dd>++<dl>+<dd>++A single MCP server as the slim chat projection, with live per-user auth_status.+</dd>+</dl>+</dd>+</dl>++#### π Usage++<dl>+<dd>++<dl>+<dd>++```typescript+await client.mcpServers.get("name");++```+</dd>+</dl>+</dd>+</dl>++#### βοΈ Parameters++<dl>+<dd>++<dl>+<dd>++**name:** `string` β MCP server name.++</dd>+</dl>++<dl>+<dd>++**requestOptions:** `McpServersClient.RequestOptions`++</dd>+</dl>+</dd>+</dl>++</dd></dl></details>diff --git a/packages/trueforge-sdk/src/api/resources/mcpServers/client/Client.ts b/packages/trueforge-sdk/src/api/resources/mcpServers/client/Client.tsindex e72285989..38dd38cac 100644--- a/packages/trueforge-sdk/src/api/resources/mcpServers/client/Client.ts+++ b/packages/trueforge-sdk/src/api/resources/mcpServers/client/Client.ts@@ -135,6 +135,101 @@ export class McpServersClient {});}+ /**+ * A single MCP server as the slim chat projection, with live per-user auth_status.+ *+ * @param {string} name - MCP server name.+ * @param {McpServersClient.RequestOptions} requestOptions - Request-specific configuration.+ *+ * @throws {@link TrueForge.UnauthorizedError}+ * @throws {@link TrueForge.NotFoundError}+ * @throws {@link errors.TrueForgeError}+ * @throws {@link errors.TrueForgeTimeoutError}+ *+ * @example+ * await client.mcpServers.get("name")+ */+ public get(+ name: string,+ requestOptions?: McpServersClient.RequestOptions,+ ): core.HttpResponsePromise<TrueForge.GetAvailableMcpServerResponse> {+ return core.HttpResponsePromise.fromPromise(this.__get(name, requestOptions));+ }++ private async __get(+ name: string,+ requestOptions?: McpServersClient.RequestOptions,+ ): Promise<core.WithRawResponse<TrueForge.GetAvailableMcpServerResponse>> {+ const _authRequest: core.AuthRequest = await this._options.authProvider.getAuthRequest();+ const _headers: core.Fetcher.Args["headers"] = mergeHeaders(+ _authRequest.headers,+ this._options?.headers,+ requestOptions?.headers,+ );+ const _response = await (this._options.fetcher ?? core.fetcher)({+ url: core.url.join(+ (await core.Supplier.get(this._options.baseUrl)) ??+ (await core.Supplier.get(this._options.environment)),+ `api/v1/mcp-servers/${core.url.encodePathParam(name)}`,+ ),+ method: "GET",+ headers: _headers,+ queryString: core.url.queryBuilder().mergeAdditional(requestOptions?.queryParams).build(),+ timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1000,+ maxRetries: requestOptions?.maxRetries ?? this._options?.maxRetries,+ abortSignal: requestOptions?.abortSignal,+ fetchFn: this._options?.fetch,+ logging: this._options.logging,+ });+ if (_response.ok) {+ return {+ data: serializers.GetAvailableMcpServerResponse.parseOrThrow(_response.body, {+ unrecognizedObjectKeys: "passthrough",+ allowUnrecognizedUnionMembers: true,+ allowUnrecognizedEnumValues: true,+ skipValidation: true,+ breadcrumbsPrefix: ["response"],+ }),+ rawResponse: _response.rawResponse,+ };+ }++ if (_response.error.reason === "status-code") {+ switch (_response.error.statusCode) {+ case 401:+ throw new TrueForge.UnauthorizedError(+ serializers.RequestErrorResponse.parseOrThrow(_response.error.body, {+ unrecognizedObjectKeys: "passthrough",+ allowUnrecognizedUnionMembers: true,+ allowUnrecognizedEnumValues: true,+ skipValidation: true,+ breadcrumbsPrefix: ["response"],+ }),+ _response.rawResponse,+ );+ case 404:+ throw new TrueForge.NotFoundError(+ serializers.RequestErrorResponse.parseOrThrow(_response.error.body, {+ unrecognizedObjectKeys: "passthrough",+ allowUnrecognizedUnionMembers: true,+ allowUnrecognizedEnumValues: true,+ skipValidation: true,+ breadcrumbsPrefix: ["response"],+ }),+ _response.rawResponse,+ );+ default:+ throw new errors.TrueForgeError({+ statusCode: _response.error.statusCode,+ body: _response.error.body,+ rawResponse: _response.rawResponse,+ });+ }+ }++ return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/api/v1/mcp-servers/{name}");+ }+/*** Returns current auth status. When OAuth is required, includes an authorization URL. Optional return_to is the post-consent landing path.*diff --git a/packages/trueforge-sdk/src/api/types/GetAvailableMcpServerResponse.ts b/packages/trueforge-sdk/src/api/types/GetAvailableMcpServerResponse.tsnew file mode 100644index 000000000..8dd4bff3b--- /dev/null+++ b/packages/trueforge-sdk/src/api/types/GetAvailableMcpServerResponse.ts@@ -0,0 +1,7 @@+// This file was auto-generated by Fern from our API Definition.++import type * as TrueForge from "../index.js";++export interface GetAvailableMcpServerResponse {+ data: TrueForge.AvailableMcpServer;+}diff --git a/packages/trueforge-sdk/src/api/types/index.ts b/packages/trueforge-sdk/src/api/types/index.tsindex c1114ffdd..18a612fbb 100644--- a/packages/trueforge-sdk/src/api/types/index.ts+++ b/packages/trueforge-sdk/src/api/types/index.ts@@ -58,6 +58,7 @@ export * from "./FireworksModelProvider.js";export * from "./GenerativeUiConfig.js";export * from "./GetAgentCodeSnippetsResponse.js";export * from "./GetAgentResponse.js";+export * from "./GetAvailableMcpServerResponse.js";export * from "./GetCapabilitiesResponse.js";export * from "./GetMcpServerCatalogResponse.js";export * from "./GetMcpServerResponse.js";diff --git a/packages/trueforge-sdk/src/serialization/types/GetAvailableMcpServerResponse.ts b/packages/trueforge-sdk/src/serialization/types/GetAvailableMcpServerResponse.tsnew file mode 100644index 000000000..d5de5b240--- /dev/null+++ b/packages/trueforge-sdk/src/serialization/types/GetAvailableMcpServerResponse.ts@@ -0,0 +1,19 @@+// This file was auto-generated by Fern from our API Definition.++import type * as TrueForge from "../../api/index.js";+import * as core from "../../core/index.js";+import type * as serializers from "../index.js";+import { AvailableMcpServer } from "./AvailableMcpServer.js";++export const GetAvailableMcpServerResponse: core.serialization.ObjectSchema<+ serializers.GetAvailableMcpServerResponse.Raw,+ TrueForge.GetAvailableMcpServerResponse+> = core.serialization.object({+ data: AvailableMcpServer,+});++export declare namespace GetAvailableMcpServerResponse {+ export interface Raw {+ data: AvailableMcpServer.Raw;+ }+}diff --git a/packages/trueforge-sdk/src/serialization/types/index.ts b/packages/trueforge-sdk/src/serialization/types/index.tsindex c1114ffdd..18a612fbb 100644--- a/packages/trueforge-sdk/src/serialization/types/index.ts+++ b/packages/trueforge-sdk/src/serialization/types/index.ts@@ -58,6 +58,7 @@ export * from "./FireworksModelProvider.js";export * from "./GenerativeUiConfig.js";export * from "./GetAgentCodeSnippetsResponse.js";export * from "./GetAgentResponse.js";+export * from "./GetAvailableMcpServerResponse.js";export * from "./GetCapabilitiesResponse.js";export * from "./GetMcpServerCatalogResponse.js";export * from "./GetMcpServerResponse.js";diff --git a/packages/trueforge-sdk/tests/wire/mcpServers.test.ts b/packages/trueforge-sdk/tests/wire/mcpServers.test.tsindex 7481d6b7e..8fc4e7b99 100644--- a/packages/trueforge-sdk/tests/wire/mcpServers.test.ts+++ b/packages/trueforge-sdk/tests/wire/mcpServers.test.ts@@ -87,6 +87,81 @@ describe("McpServersClient", () => {}).rejects.toThrow(TrueForgeTypes.UnauthorizedError);});+ test("get (1)", async () => {+ const server = mockServerPool.createServer();+ const client = new TrueForge({ maxRetries: 0, token: "test", baseUrl: server.baseUrl });++ const rawResponseBody = {+ data: {+ auth: { type: "dcr" },+ auth_status: { authorization_url: "authorization_url", status: "authenticated" },+ name: "name",+ url: "url",+ },+ };++ server+ .mockEndpoint()+ .get("/api/v1/mcp-servers/name")+ .respondWith()+ .statusCode(200)+ .jsonBody(rawResponseBody)+ .build();++ const response = await client.mcpServers.get("name");+ expect(response).toEqual({+ data: {+ auth: {+ type: "dcr",+ },+ authStatus: {+ authorizationUrl: "authorization_url",+ status: "authenticated",+ },+ name: "name",+ url: "url",+ },+ });+ });++ test("get (2)", async () => {+ const server = mockServerPool.createServer();+ const client = new TrueForge({ maxRetries: 0, token: "test", baseUrl: server.baseUrl });++ const rawResponseBody = { error: { message: "message" } };++ server+ .mockEndpoint()+ .get("/api/v1/mcp-servers/name")+ .respondWith()+ .statusCode(401)+ .jsonBody(rawResponseBody)+ .build();++ await expect(async () => {+ return await client.mcpServers.get("name");+ }).rejects.toThrow(TrueForgeTypes.UnauthorizedError);+ });++ test("get (3)", async () => {+ const server = mockServerPool.createServer();+ const client = new TrueForge({ maxRetries: 0, token: "test", baseUrl: server.baseUrl });++ const rawResponseBody = { error: { message: "message" } };++ server+ .mockEndpoint()+ .get("/api/v1/mcp-servers/name")+ .respondWith()+ .statusCode(404)+ .jsonBody(rawResponseBody)+ .build();++ await expect(async () => {+ return await client.mcpServers.get("name");+ }).rejects.toThrow(TrueForgeTypes.NotFoundError);+ });+test("authorize (1)", async () => {const server = mockServerPool.createServer();const client = new TrueForge({ maxRetries: 0, token: "test", baseUrl: server.baseUrl });diff --git a/packages/trueforge/src/apis/mcpServers.ts b/packages/trueforge/src/apis/mcpServers.tsindex ca5ea1395..42ad71025 100644--- a/packages/trueforge/src/apis/mcpServers.ts+++ b/packages/trueforge/src/apis/mcpServers.ts@@ -21,6 +21,7 @@ import {authorizeMcpServerRoute,createMcpServerRoute,deleteAuthorizationMcpServerRoute,+ getAvailableMcpServerRoute,getMcpServerRoute,listAvailableMcpServersRoute,listMcpServersRoute,@@ -117,6 +118,31 @@ async function toConfiguredMcpServer<TTransaction>(params: {};}+function toAvailableMcpServer(params: { record: McpServerRecord; authStatus: McpAuthStatus }): AvailableMcpServer {+ const authType = params.record.manifest.auth?.type;+ return {+ name: params.record.name,+ url: params.record.manifest.url,+ ...(authType !== undefined ? { auth: { type: authType } } : {}),+ auth_status: params.authStatus,+ };+}++async function resolveAvailableMcpServer<TTransaction>(params: {+ store: IMcpServerWithAuthStore<TTransaction>;+ record: McpServerRecord;+ userRef: string;+}): Promise<AvailableMcpServer> {+ const statuses = await params.store.resolveAuthStatuses({+ records: [params.record],+ userRef: params.userRef,+ });+ return toAvailableMcpServer({+ record: params.record,+ authStatus: statuses.get(params.record.name) ?? { status: 'auth_required' },+ });+}+/** Admin/settings MCP CRUD. */export function createSettingsMcpServersRouter<TTransaction>(deps: McpServersRouterDeps<TTransaction>) {const listHandler: RouteHandler<typeof listMcpServersRoute> = async c => {@@ -460,6 +486,28 @@ export function createMcpServersRouter<TTransaction>(deps: McpServersRouterDeps<}};+ const getAvailableHandler: RouteHandler<typeof getAvailableMcpServerRoute> = async c => {+ const { name } = c.req.valid('param');+ const requestContext = deps.resolveRequestContext(c);+ const record = await deps.resolveMcpServerStore(c).getServer({+ tenant_id: requestContext.tenant_id,+ name,+ });+ if (!record) {+ return c.json({ error: { message: `MCP server not found: ${name}` } }, 404);+ }+ return c.json(+ {+ data: await resolveAvailableMcpServer({+ store: deps.resolveMcpServerStore(c),+ record,+ userRef: requestContext.subject.id,+ }),+ },+ 200,+ );+ };+const router = new OpenAPIHono();router.openapi(listAvailableMcpServersRoute, async c => {const requestContext = deps.resolveRequestContext(c);@@ -476,15 +524,12 @@ export function createMcpServersRouter<TTransaction>(deps: McpServersRouterDeps<records,userRef,});- const data: AvailableMcpServer[] = records.map(record => {- const authType = record.manifest.auth?.type;- return {- name: record.name,- url: record.manifest.url,- ...(authType !== undefined ? { auth: { type: authType } } : {}),- auth_status: statuses.get(record.name) ?? { status: 'auth_required' },- };- });+ const data: AvailableMcpServer[] = records.map(record =>+ toAvailableMcpServer({+ record,+ authStatus: statuses.get(record.name) ?? { status: 'auth_required' },+ }),+ );return c.json({ data, pagination }, 200);} catch (error) {if (error instanceof InvalidPageTokenError) {@@ -496,5 +541,6 @@ export function createMcpServersRouter<TTransaction>(deps: McpServersRouterDeps<router.openapi(listMcpServerToolsRoute, listToolsHandler);router.openapi(authorizeMcpServerRoute, authorizeHandler);router.openapi(deleteAuthorizationMcpServerRoute, deleteAuthorizationHandler);+ router.openapi(getAvailableMcpServerRoute, getAvailableHandler);return router;}diff --git a/packages/trueforge/src/routes/mcpServerRoutes.ts b/packages/trueforge/src/routes/mcpServerRoutes.tsindex a03a0a9d2..5cd701842 100644--- a/packages/trueforge/src/routes/mcpServerRoutes.ts+++ b/packages/trueforge/src/routes/mcpServerRoutes.ts@@ -3,6 +3,7 @@ import { MCP_SERVERS_PAGE_LIMIT, MCP_SERVERS_PAGE_LIMIT_MAX } from '../schemas/cimport { RequestErrorResponseSchema } from '../schemas/errors';import {CreateMcpServerRequestSchema,+ GetAvailableMcpServerResponseSchema,GetMcpServerResponseSchema,ListAvailableMcpServersResponseSchema,ListMcpServersResponseSchema,@@ -26,6 +27,10 @@ export const ListMcpServersQuerySchema = z}).openapi('ListMCPServersQuery');+const McpServerNameParamsSchema = z.object({+ name: z.string().min(1).describe('MCP server name.'),+});+/** Chat/composer MCP list (not under settings). */export const listAvailableMcpServersRoute = createRoute({method: 'get',@@ -55,6 +60,34 @@ export const listAvailableMcpServersRoute = createRoute({},});+/** Chat/composer single-server read (not under settings). */+export const getAvailableMcpServerRoute = createRoute({+ method: 'get',+ path: '/{name}',+ tags: [OpenApiTag.MCP_SERVERS],+ summary: 'Get an MCP server for chat',+ description: 'A single MCP server as the slim chat projection, with live per-user auth_status.',+ 'x-fern-sdk-group-name': ['mcpServers'],+ 'x-fern-sdk-method-name': 'get',+ request: {+ params: McpServerNameParamsSchema,+ },+ responses: {+ 200: {+ content: { 'application/json': { schema: GetAvailableMcpServerResponseSchema } },+ description: 'The MCP server (chat projection).',+ },+ 401: {+ content: { 'application/json': { schema: RequestErrorResponseSchema } },+ description: 'OIDC is configured and the request has no valid session cookie.',+ },+ 404: {+ content: { 'application/json': { schema: RequestErrorResponseSchema } },+ description: 'MCP server not found.',+ },+ },+});+export const listMcpServersRoute = createRoute({method: 'get',path: '/',@@ -87,10 +120,6 @@ export const listMcpServersRoute = createRoute({},});-const McpServerNameParamsSchema = z.object({- name: z.string().min(1).describe('MCP server name.'),-});-export const getMcpServerRoute = createRoute({method: 'get',path: '/{name}',diff --git a/packages/trueforge/src/schemas/mcpServer.ts b/packages/trueforge/src/schemas/mcpServer.tsindex edca4ccc1..91fc62e95 100644--- a/packages/trueforge/src/schemas/mcpServer.ts+++ b/packages/trueforge/src/schemas/mcpServer.ts@@ -138,6 +138,10 @@ export const ListAvailableMcpServersResponseSchema = z}).openapi('ListAvailableMCPServersResponse');+export const GetAvailableMcpServerResponseSchema = z+ .object({ data: AvailableMcpServerSchema })+ .openapi('GetAvailableMCPServerResponse');+export type McpServerType = z.infer<typeof McpServerTypeSchema>;export type McpServerManifestAuth = z.infer<typeof McpServerManifestAuthSchema>;export type McpServerManifest = z.infer<typeof McpServerManifestSchema>;diff --git a/packages/trueforge/tests/unit/apis/mcpServers.test.ts b/packages/trueforge/tests/unit/apis/mcpServers.test.tsindex ceba2d00f..19ed21755 100644--- a/packages/trueforge/tests/unit/apis/mcpServers.test.ts+++ b/packages/trueforge/tests/unit/apis/mcpServers.test.ts@@ -646,6 +646,43 @@ describe('mcp-servers routers', () => {});});+ it('GET /{name} on the chat router returns the slim projection with live auth_status', async () => {+ const missing = await mcpServersRouter.request('/missing-server');+ expect(missing.status).toBe(404);++ const noAuth = await mcpServersRouter.request('/deepwiki');+ expect(noAuth.status).toBe(200);+ expect(await noAuth.json()).toEqual({+ data: {+ name: 'deepwiki',+ url: putBody.url,+ auth_status: { status: 'not_required' },+ },+ });++ const dcr = await mcpServersRouter.request('/linear');+ expect(dcr.status).toBe(200);+ expect(await dcr.json()).toEqual({+ data: {+ name: 'linear',+ url: putBodyWithDcr.url,+ auth: { type: 'dcr' },+ auth_status: { status: 'auth_required' },+ },+ });++ const headerAuth = await mcpServersRouter.request('/private-mcp');+ expect(headerAuth.status).toBe(200);+ expect(await headerAuth.json()).toEqual({+ data: {+ name: 'private-mcp',+ url: putBodyWithHeaderAuth.url,+ auth: { type: 'header' },+ auth_status: { status: 'authenticated' },+ },+ });+ });+it('GET / chat list auth_status is scoped to the calling user', async () => {const record = await mcpServerStore.getServer({ tenant_id: 'default', name: putBodyWithDcr.name });if (record === undefined) throw new Error('expected DCR server to exist');