Skip to content

The open-source agent harness - the runtime layer that turns an LLM into a working agent.

feat: add description to connectors (#228)

Srajan Asthana2aa515ed1955
diff --git a/.github/fern/openapi/openapi.json b/.github/fern/openapi/openapi.json
index cbd8f02d1..9b6a5f363 100644
--- a/.github/fern/openapi/openapi.json
+++ b/.github/fern/openapi/openapi.json
@@ -435,6 +435,11 @@
"auth": {
"$ref": "#/components/schemas/ConfiguredMcpServerAuth"
},
+ "description": {
+ "description": "Concise summary of what this MCP server provides.",
+ "minLength": 1,
+ "type": "string"
+ },
"logo": {
"description": "URL of the MCP server logo asset.",
"format": "uri",
@@ -462,7 +467,8 @@
"required": [
"type",
"name",
- "url"
+ "url",
+ "description"
],
"type": "object"
},
@@ -694,6 +700,11 @@
"auth_status": {
"$ref": "#/components/schemas/McpAuthStatus"
},
+ "description": {
+ "description": "Concise summary of what this MCP server provides.",
+ "minLength": 1,
+ "type": "string"
+ },
"name": {
"allOf": [
{
@@ -717,6 +728,7 @@
"type",
"name",
"url",
+ "description",
"auth_status"
],
"type": "object"
@@ -809,6 +821,11 @@
}
]
},
+ "description": {
+ "description": "Concise summary of what this MCP server provides.",
+ "minLength": 1,
+ "type": "string"
+ },
"name": {
"allOf": [
{
@@ -831,7 +848,8 @@
"required": [
"type",
"name",
- "url"
+ "url",
+ "description"
],
"type": "object"
},
@@ -1841,6 +1859,11 @@
}
]
},
+ "description": {
+ "description": "Concise summary of what this MCP server provides.",
+ "minLength": 1,
+ "type": "string"
+ },
"name": {
"allOf": [
{
@@ -1863,7 +1886,8 @@
"required": [
"type",
"name",
- "url"
+ "url",
+ "description"
],
"type": "object"
},
diff --git a/packages/sdk/reference.md b/packages/sdk/reference.md
index 1608f02c4..de568c117 100644
--- a/packages/sdk/reference.md
+++ b/packages/sdk/reference.md
@@ -2112,6 +2112,7 @@ Creates an MCP server by `name`. Fails if `name` is already taken. Runs DCR regi
```typescript
await client.settings.mcpServers.create({
+ description: "description",
name: "name",
url: "url"
});
@@ -2178,6 +2179,7 @@ Create or replace by `name`. Does not start DCR or change oauth client columns.
```typescript
await client.settings.mcpServers.upsert({
+ description: "description",
name: "name",
url: "url"
});
diff --git a/packages/sdk/src/api/resources/settings/resources/mcpServers/client/Client.ts b/packages/sdk/src/api/resources/settings/resources/mcpServers/client/Client.ts
index f8b349af6..810e52a8d 100644
--- a/packages/sdk/src/api/resources/settings/resources/mcpServers/client/Client.ts
+++ b/packages/sdk/src/api/resources/settings/resources/mcpServers/client/Client.ts
@@ -129,6 +129,7 @@ export class McpServersClient {
*
* @example
* await client.settings.mcpServers.create({
+ * description: "description",
* name: "name",
* url: "url"
* })
@@ -252,6 +253,7 @@ export class McpServersClient {
*
* @example
* await client.settings.mcpServers.upsert({
+ * description: "description",
* name: "name",
* url: "url"
* })
diff --git a/packages/sdk/src/api/resources/settings/resources/mcpServers/client/requests/CreateMcpServerRequest.ts b/packages/sdk/src/api/resources/settings/resources/mcpServers/client/requests/CreateMcpServerRequest.ts
index 8ff7dfef2..25c457a57 100644
--- a/packages/sdk/src/api/resources/settings/resources/mcpServers/client/requests/CreateMcpServerRequest.ts
+++ b/packages/sdk/src/api/resources/settings/resources/mcpServers/client/requests/CreateMcpServerRequest.ts
@@ -5,6 +5,7 @@ import type * as TrueForge from "../../../../../../index.js";
/**
* @example
* {
+ * description: "description",
* name: "name",
* url: "url"
* }
@@ -12,6 +13,8 @@ import type * as TrueForge from "../../../../../../index.js";
export interface CreateMcpServerRequest {
/** Optional auth settings. Omit when the server needs no credentials. */
auth?: TrueForge.settings.CreateMcpServerRequestAuth;
+ /** Concise summary of what this MCP server provides. */
+ description: string;
/** Fully qualified name. Unique within a tenant. */
name: string;
/** URL of the remote MCP server. */
diff --git a/packages/sdk/src/api/resources/settings/resources/mcpServers/client/requests/McpServerManifest.ts b/packages/sdk/src/api/resources/settings/resources/mcpServers/client/requests/McpServerManifest.ts
index 38b2fb2d1..2bf058c7b 100644
--- a/packages/sdk/src/api/resources/settings/resources/mcpServers/client/requests/McpServerManifest.ts
+++ b/packages/sdk/src/api/resources/settings/resources/mcpServers/client/requests/McpServerManifest.ts
@@ -5,6 +5,7 @@ import type * as TrueForge from "../../../../../../index.js";
/**
* @example
* {
+ * description: "description",
* name: "name",
* url: "url"
* }
@@ -12,6 +13,8 @@ import type * as TrueForge from "../../../../../../index.js";
export interface McpServerManifest {
/** Optional auth settings. Omit when the server needs no credentials. */
auth?: TrueForge.settings.McpServerManifestAuth;
+ /** Concise summary of what this MCP server provides. */
+ description: string;
/** Fully qualified name. Unique within a tenant. */
name: string;
/** URL of the remote MCP server. */
diff --git a/packages/sdk/src/api/types/CatalogMcpServer.ts b/packages/sdk/src/api/types/CatalogMcpServer.ts
index 9299b326a..c1b9e2280 100644
--- a/packages/sdk/src/api/types/CatalogMcpServer.ts
+++ b/packages/sdk/src/api/types/CatalogMcpServer.ts
@@ -4,6 +4,8 @@ import type * as TrueForge from "../index.js";
export interface CatalogMcpServer {
auth?: TrueForge.ConfiguredMcpServerAuth;
+ /** Concise summary of what this MCP server provides. */
+ description: string;
/** URL of the MCP server logo asset. */
logo?: string;
/** Fully qualified name. Unique within a tenant. */
diff --git a/packages/sdk/src/api/types/ConfiguredMcpServer.ts b/packages/sdk/src/api/types/ConfiguredMcpServer.ts
index 4bbe32fba..ce6197687 100644
--- a/packages/sdk/src/api/types/ConfiguredMcpServer.ts
+++ b/packages/sdk/src/api/types/ConfiguredMcpServer.ts
@@ -6,6 +6,8 @@ export interface ConfiguredMcpServer {
/** Optional auth settings. Omit when the server needs no credentials. */
auth?: TrueForge.ConfiguredMcpServerAuth;
authStatus: TrueForge.McpAuthStatus;
+ /** Concise summary of what this MCP server provides. */
+ description: string;
/** Fully qualified name. Unique within a tenant. */
name: string;
type: TrueForge.McpServerType;
diff --git a/packages/sdk/src/serialization/resources/settings/resources/mcpServers/client/requests/CreateMcpServerRequest.ts b/packages/sdk/src/serialization/resources/settings/resources/mcpServers/client/requests/CreateMcpServerRequest.ts
index b2d21b153..c1d7719e2 100644
--- a/packages/sdk/src/serialization/resources/settings/resources/mcpServers/client/requests/CreateMcpServerRequest.ts
+++ b/packages/sdk/src/serialization/resources/settings/resources/mcpServers/client/requests/CreateMcpServerRequest.ts
@@ -10,6 +10,7 @@ export const CreateMcpServerRequest: core.serialization.Schema<
TrueForge.settings.CreateMcpServerRequest
> = core.serialization.object({
auth: CreateMcpServerRequestAuth.optional(),
+ description: core.serialization.string(),
name: core.serialization.string(),
url: core.serialization.string(),
});
@@ -17,6 +18,7 @@ export const CreateMcpServerRequest: core.serialization.Schema<
export declare namespace CreateMcpServerRequest {
export interface Raw {
auth?: CreateMcpServerRequestAuth.Raw | null;
+ description: string;
name: string;
url: string;
}
diff --git a/packages/sdk/src/serialization/resources/settings/resources/mcpServers/client/requests/McpServerManifest.ts b/packages/sdk/src/serialization/resources/settings/resources/mcpServers/client/requests/McpServerManifest.ts
index 5f46d56cf..b56714385 100644
--- a/packages/sdk/src/serialization/resources/settings/resources/mcpServers/client/requests/McpServerManifest.ts
+++ b/packages/sdk/src/serialization/resources/settings/resources/mcpServers/client/requests/McpServerManifest.ts
@@ -10,6 +10,7 @@ export const McpServerManifest: core.serialization.Schema<
TrueForge.settings.McpServerManifest
> = core.serialization.object({
auth: McpServerManifestAuth.optional(),
+ description: core.serialization.string(),
name: core.serialization.string(),
url: core.serialization.string(),
});
@@ -17,6 +18,7 @@ export const McpServerManifest: core.serialization.Schema<
export declare namespace McpServerManifest {
export interface Raw {
auth?: McpServerManifestAuth.Raw | null;
+ description: string;
name: string;
url: string;
}
diff --git a/packages/sdk/src/serialization/types/CatalogMcpServer.ts b/packages/sdk/src/serialization/types/CatalogMcpServer.ts
index 123178409..27f7a835e 100644
--- a/packages/sdk/src/serialization/types/CatalogMcpServer.ts
+++ b/packages/sdk/src/serialization/types/CatalogMcpServer.ts
@@ -11,6 +11,7 @@ export const CatalogMcpServer: core.serialization.ObjectSchema<
TrueForge.CatalogMcpServer
> = core.serialization.object({
auth: ConfiguredMcpServerAuth.optional(),
+ description: core.serialization.string(),
logo: core.serialization.string().optional(),
name: core.serialization.string(),
type: McpServerType,
@@ -20,6 +21,7 @@ export const CatalogMcpServer: core.serialization.ObjectSchema<
export declare namespace CatalogMcpServer {
export interface Raw {
auth?: ConfiguredMcpServerAuth.Raw | null;
+ description: string;
logo?: string | null;
name: string;
type: McpServerType.Raw;
diff --git a/packages/sdk/src/serialization/types/ConfiguredMcpServer.ts b/packages/sdk/src/serialization/types/ConfiguredMcpServer.ts
index 2960414e2..3f4d35fba 100644
--- a/packages/sdk/src/serialization/types/ConfiguredMcpServer.ts
+++ b/packages/sdk/src/serialization/types/ConfiguredMcpServer.ts
@@ -13,6 +13,7 @@ export const ConfiguredMcpServer: core.serialization.ObjectSchema<
> = core.serialization.object({
auth: ConfiguredMcpServerAuth.optional(),
authStatus: core.serialization.property("auth_status", McpAuthStatus),
+ description: core.serialization.string(),
name: core.serialization.string(),
type: McpServerType,
url: core.serialization.string(),
@@ -22,6 +23,7 @@ export declare namespace ConfiguredMcpServer {
export interface Raw {
auth?: ConfiguredMcpServerAuth.Raw | null;
auth_status: McpAuthStatus.Raw;
+ description: string;
name: string;
type: McpServerType.Raw;
url: string;
diff --git a/packages/sdk/tests/wire/catalog/mcpServers.test.ts b/packages/sdk/tests/wire/catalog/mcpServers.test.ts
index 67e7c6b87..b54926ffd 100644
--- a/packages/sdk/tests/wire/catalog/mcpServers.test.ts
+++ b/packages/sdk/tests/wire/catalog/mcpServers.test.ts
@@ -10,7 +10,16 @@ describe("McpServersClient", () => {
const client = new TrueForge({ maxRetries: 0, token: "test", baseUrl: server.baseUrl });
const rawResponseBody = {
- data: [{ auth: { type: "dcr" }, logo: "logo", name: "name", type: "remote", url: "url" }],
+ data: [
+ {
+ auth: { type: "dcr" },
+ description: "description",
+ logo: "logo",
+ name: "name",
+ type: "remote",
+ url: "url",
+ },
+ ],
};
server
@@ -28,6 +37,7 @@ describe("McpServersClient", () => {
auth: {
type: "dcr",
},
+ description: "description",
logo: "logo",
name: "name",
type: "remote",
diff --git a/packages/sdk/tests/wire/mcpServers.test.ts b/packages/sdk/tests/wire/mcpServers.test.ts
index 99a4957b1..324552a33 100644
--- a/packages/sdk/tests/wire/mcpServers.test.ts
+++ b/packages/sdk/tests/wire/mcpServers.test.ts
@@ -181,6 +181,7 @@ describe("McpServersClient", () => {
data: {
auth: { type: "dcr" },
auth_status: { authorization_url: "authorization_url", status: "authenticated" },
+ description: "description",
name: "name",
type: "remote",
url: "url",
@@ -205,6 +206,7 @@ describe("McpServersClient", () => {
authorizationUrl: "authorization_url",
status: "authenticated",
},
+ description: "description",
name: "name",
type: "remote",
url: "url",
diff --git a/packages/sdk/tests/wire/settings/mcpServers.test.ts b/packages/sdk/tests/wire/settings/mcpServers.test.ts
index 8dd732bfc..f7eb05c42 100644
--- a/packages/sdk/tests/wire/settings/mcpServers.test.ts
+++ b/packages/sdk/tests/wire/settings/mcpServers.test.ts
@@ -14,6 +14,7 @@ describe("McpServersClient", () => {
{
auth: { type: "dcr" },
auth_status: { status: "authenticated" },
+ description: "description",
name: "name",
type: "remote",
url: "url",
@@ -39,6 +40,7 @@ describe("McpServersClient", () => {
authStatus: {
status: "authenticated",
},
+ description: "description",
name: "name",
type: "remote",
url: "url",
@@ -88,11 +90,12 @@ describe("McpServersClient", () => {
test("create (1)", async () => {
const server = mockServerPool.createServer();
const client = new TrueForge({ maxRetries: 0, token: "test", baseUrl: server.baseUrl });
- const rawRequestBody = { name: "name", type: "remote", url: "url" };
+ const rawRequestBody = { description: "description", name: "name", type: "remote", url: "url" };
const rawResponseBody = {
data: {
auth: { type: "dcr" },
auth_status: { authorization_url: "authorization_url", status: "authenticated" },
+ description: "description",
name: "name",
type: "remote",
url: "url",
@@ -109,6 +112,7 @@ describe("McpServersClient", () => {
.build();
const response = await client.settings.mcpServers.create({
+ description: "description",
name: "name",
url: "url",
});
@@ -121,6 +125,7 @@ describe("McpServersClient", () => {
authorizationUrl: "authorization_url",
status: "authenticated",
},
+ description: "description",
name: "name",
type: "remote",
url: "url",
@@ -131,7 +136,7 @@ describe("McpServersClient", () => {
test("create (2)", async () => {
const server = mockServerPool.createServer();
const client = new TrueForge({ maxRetries: 0, token: "test", baseUrl: server.baseUrl });
- const rawRequestBody = { name: "xy", type: "remote", url: "url" };
+ const rawRequestBody = { description: "x", name: "xy", type: "remote", url: "url" };
const rawResponseBody = { error: { message: "message" } };
server
@@ -145,6 +150,7 @@ describe("McpServersClient", () => {
await expect(async () => {
return await client.settings.mcpServers.create({
+ description: "x",
name: "xy",
url: "url",
});
@@ -154,7 +160,7 @@ describe("McpServersClient", () => {
test("create (3)", async () => {
const server = mockServerPool.createServer();
const client = new TrueForge({ maxRetries: 0, token: "test", baseUrl: server.baseUrl });
- const rawRequestBody = { name: "xy", type: "remote", url: "url" };
+ const rawRequestBody = { description: "x", name: "xy", type: "remote", url: "url" };
const rawResponseBody = { error: { message: "message" } };
server
@@ -168,6 +174,7 @@ describe("McpServersClient", () => {
await expect(async () => {
return await client.settings.mcpServers.create({
+ description: "x",
name: "xy",
url: "url",
});
@@ -177,7 +184,7 @@ describe("McpServersClient", () => {
test("create (4)", async () => {
const server = mockServerPool.createServer();
const client = new TrueForge({ maxRetries: 0, token: "test", baseUrl: server.baseUrl });
- const rawRequestBody = { name: "xy", type: "remote", url: "url" };
+ const rawRequestBody = { description: "x", name: "xy", type: "remote", url: "url" };
const rawResponseBody = { error: { message: "message" } };
server
@@ -191,6 +198,7 @@ describe("McpServersClient", () => {
await expect(async () => {
return await client.settings.mcpServers.create({
+ description: "x",
name: "xy",
url: "url",
});
@@ -200,11 +208,12 @@ describe("McpServersClient", () => {
test("upsert (1)", async () => {
const server = mockServerPool.createServer();
const client = new TrueForge({ maxRetries: 0, token: "test", baseUrl: server.baseUrl });
- const rawRequestBody = { name: "name", type: "remote", url: "url" };
+ const rawRequestBody = { description: "description", name: "name", type: "remote", url: "url" };
const rawResponseBody = {
data: {
auth: { type: "dcr" },
auth_status: { authorization_url: "authorization_url", status: "authenticated" },
+ description: "description",
name: "name",
type: "remote",
url: "url",
@@ -221,6 +230,7 @@ describe("McpServersClient", () => {
.build();
const response = await client.settings.mcpServers.upsert({
+ description: "description",
name: "name",
url: "url",
});
@@ -233,6 +243,7 @@ describe("McpServersClient", () => {
authorizationUrl: "authorization_url",
status: "authenticated",
},
+ description: "description",
name: "name",
type: "remote",
url: "url",
@@ -243,7 +254,7 @@ describe("McpServersClient", () => {
test("upsert (2)", async () => {
const server = mockServerPool.createServer();
const client = new TrueForge({ maxRetries: 0, token: "test", baseUrl: server.baseUrl });
- const rawRequestBody = { name: "xy", type: "remote", url: "url" };
+ const rawRequestBody = { description: "x", name: "xy", type: "remote", url: "url" };
const rawResponseBody = { error: { message: "message" } };
server
@@ -257,6 +268,7 @@ describe("McpServersClient", () => {
await expect(async () => {
return await client.settings.mcpServers.upsert({
+ description: "x",
name: "xy",
url: "url",
});
@@ -266,7 +278,7 @@ describe("McpServersClient", () => {
test("upsert (3)", async () => {
const server = mockServerPool.createServer();
const client = new TrueForge({ maxRetries: 0, token: "test", baseUrl: server.baseUrl });
- const rawRequestBody = { name: "xy", type: "remote", url: "url" };
+ const rawRequestBody = { description: "x", name: "xy", type: "remote", url: "url" };
const rawResponseBody = { error: { message: "message" } };
server
@@ -280,6 +292,7 @@ describe("McpServersClient", () => {
await expect(async () => {
return await client.settings.mcpServers.upsert({
+ description: "x",
name: "xy",
url: "url",
});
@@ -294,6 +307,7 @@ describe("McpServersClient", () => {
data: {
auth: { type: "dcr" },
auth_status: { authorization_url: "authorization_url", status: "authenticated" },
+ description: "description",
name: "name",
type: "remote",
url: "url",
@@ -318,6 +332,7 @@ describe("McpServersClient", () => {
authorizationUrl: "authorization_url",
status: "authenticated",
},
+ description: "description",
name: "name",
type: "remote",
url: "url",
diff --git a/packages/server/catalog/mcp-catalog.yaml b/packages/server/catalog/mcp-catalog.yaml
index 0e98b779b..cafaef94f 100644
--- a/packages/server/catalog/mcp-catalog.yaml
+++ b/packages/server/catalog/mcp-catalog.yaml
@@ -6,36 +6,43 @@ mcp_servers:
name: linear
logo: https://assets.production.truefoundry.com/linear.svg
url: https://mcp.linear.app/mcp
+ description: Search, read, and create Linear issues.
auth:
type: dcr
- type: remote
name: notion
logo: https://assets.production.truefoundry.com/notion.svg
url: https://mcp.notion.com/mcp
+ description: Search pages, read content, query databases, create pages.
auth:
type: dcr
- type: remote
name: sentry
logo: https://assets.production.truefoundry.com/sentry.svg
url: https://mcp.sentry.dev/mcp
+ description: Search errors, read stack traces, and check releases.
auth:
type: dcr
- type: remote
name: deepwiki
logo: https://assets.production.truefoundry.com/deepwiki.png
url: https://mcp.deepwiki.com/mcp
+ description: Read documentation and ask questions about any public GitHub repository.
- type: remote
name: exa
logo: https://assets.production.truefoundry.com/exa.svg
url: https://mcp.exa.ai/mcp
+ description: Search the web, fetch page contents, and find similar pages.
- type: remote
name: parallel-web
logo: https://assets.production.truefoundry.com/parallel-web.svg
url: https://search.parallel.ai/mcp
+ description: Search the web and get ranked results with extracted content.
- type: remote
name: github
logo: https://assets.production.truefoundry.com/github.svg
url: https://api.githubcopilot.com/mcp/
+ description: Work with issues, pull requests, repository files, and CI status.
auth:
type: header
headers:
@@ -44,6 +51,7 @@ mcp_servers:
name: tavily
logo: https://assets.production.truefoundry.com/tavily.svg
url: https://mcp.tavily.com/mcp
+ description: Search the web, extract page content, and crawl sites.
auth:
type: header
headers:
@@ -52,6 +60,7 @@ mcp_servers:
name: bright-data
logo: https://assets.production.truefoundry.com/bright-data.png
url: https://mcp.brightdata.com/mcp
+ description: Search the web and scrape pages, including sites behind bot protection.
auth:
type: header
headers:
@@ -60,29 +69,34 @@ mcp_servers:
name: supabase
logo: https://assets.production.truefoundry.com/supabase.svg
url: https://mcp.supabase.com/mcp
+ description: Run SQL queries, manage tables, and inspect Supabase projects.
auth:
type: dcr
- type: remote
name: stripe
logo: https://assets.production.truefoundry.com/stripe.svg
url: https://mcp.stripe.com
+ description: Create and manage customers, payments, invoices, and subscriptions.
auth:
type: dcr
- type: remote
name: confluence
logo: https://assets.production.truefoundry.com/confluence.svg
url: https://mcp.atlassian.com/v1/mcp
+ description: Search spaces, read pages, and create or update content.
auth:
type: dcr
- type: remote
name: jira
logo: https://assets.production.truefoundry.com/jira.png
url: https://mcp.atlassian.com/v1/mcp
+ description: Search, read, create, and update Jira issues.
auth:
type: dcr
- type: remote
name: posthog
logo: https://assets.production.truefoundry.com/posthog.svg
url: https://mcp.posthog.com/mcp
+ description: Query product analytics, run SQL, and manage feature flags.
auth:
type: dcr
diff --git a/packages/server/src/db/postgres/migrations/20260815_000002_mcp_server_description.ts b/packages/server/src/db/postgres/migrations/20260815_000002_mcp_server_description.ts
new file mode 100644
index 000000000..2467a4e3f
--- /dev/null
+++ b/packages/server/src/db/postgres/migrations/20260815_000002_mcp_server_description.ts
@@ -0,0 +1,23 @@
+import { sql, type Kysely } from 'kysely';
+
+/**
+ * Required `description` on `mcp_server.manifest`. Backfill `{name} MCP Server`
+ * when the key is missing or blank so existing rows satisfy McpServerManifestSchema.
+ */
+export async function up(db: Kysely<unknown>): Promise<void> {
+ await sql`SET LOCAL lock_timeout = '5s'`.execute(db);
+ await sql`
+ UPDATE mcp_server
+ SET manifest = manifest || jsonb_build_object('description', name || ' MCP Server')
+ WHERE btrim(coalesce(manifest->>'description', '')) = ''
+ `.execute(db);
+}
+
+export async function down(db: Kysely<unknown>): Promise<void> {
+ await sql`SET LOCAL lock_timeout = '5s'`.execute(db);
+ await sql`
+ UPDATE mcp_server
+ SET manifest = manifest - 'description'
+ WHERE manifest->>'description' = name || ' MCP Server'
+ `.execute(db);
+}
diff --git a/packages/server/src/db/sqlite/migrations/20260815_000002_mcp_server_description.ts b/packages/server/src/db/sqlite/migrations/20260815_000002_mcp_server_description.ts
new file mode 100644
index 000000000..9fac057db
--- /dev/null
+++ b/packages/server/src/db/sqlite/migrations/20260815_000002_mcp_server_description.ts
@@ -0,0 +1,22 @@
+import { type Kysely, sql } from 'kysely';
+
+/**
+ * Required `description` on `mcp_server.manifest`. Backfill `{name} MCP Server`
+ * when the key is missing or blank so existing rows satisfy McpServerManifestSchema.
+ * Mirrors db/postgres/migrations/20260815_000002_mcp_server_description.ts.
+ */
+export async function up(db: Kysely<unknown>): Promise<void> {
+ await sql`
+ UPDATE mcp_server
+ SET manifest = jsonb_set(manifest, '$.description', jsonb(json_quote(name || ' MCP Server')))
+ WHERE trim(coalesce(json_extract(manifest, '$.description'), '')) = ''
+ `.execute(db);
+}
+
+export async function down(db: Kysely<unknown>): Promise<void> {
+ await sql`
+ UPDATE mcp_server
+ SET manifest = jsonb_remove(manifest, '$.description')
+ WHERE json_extract(manifest, '$.description') = name || ' MCP Server'
+ `.execute(db);
+}
diff --git a/packages/server/src/schemas/mcpCatalog.ts b/packages/server/src/schemas/mcpCatalog.ts
index 59e137d8f..890644b50 100644
--- a/packages/server/src/schemas/mcpCatalog.ts
+++ b/packages/server/src/schemas/mcpCatalog.ts
@@ -4,7 +4,7 @@
*/
import { z } from '@hono/zod-openapi';
import { NameSchema, uniqueNames } from './common';
-import { McpServerAuthSettingsSchema, McpServerTypeSchema } from './mcpServer';
+import { McpServerAuthSettingsSchema, McpServerDescriptionSchema, McpServerTypeSchema } from './mcpServer';
/** Catalog entry — discovery preset the settings UI copies into a PUT body. */
export const CatalogMcpServerSchema = z
@@ -13,6 +13,7 @@ export const CatalogMcpServerSchema = z
name: NameSchema,
logo: z.url().optional().describe('URL of the MCP server logo asset.'),
url: z.url().describe('URL of the remote MCP server.'),
+ description: McpServerDescriptionSchema,
auth: McpServerAuthSettingsSchema.optional().describe('Optional default auth settings for the preset.'),
})
.strict()
diff --git a/packages/server/src/schemas/mcpServer.ts b/packages/server/src/schemas/mcpServer.ts
index 26d3d8ba1..c2b7e7bf5 100644
--- a/packages/server/src/schemas/mcpServer.ts
+++ b/packages/server/src/schemas/mcpServer.ts
@@ -40,12 +40,19 @@ export const McpServerAuthSettingsSchema = z
.discriminatedUnion('type', [McpServerHeaderAuthSchema, McpServerDcrAuthSchema])
.openapi('ConfiguredMcpServerAuth');
+export const McpServerDescriptionSchema = z
+ .string()
+ .trim()
+ .min(1)
+ .describe('Concise summary of what this MCP server provides.');
+
/** Configured MCP server document persisted as `mcp_server.manifest`. */
export const McpServerManifestObjectSchema = z
.object({
type: McpServerTypeSchema.describe('MCP server kind (`remote` today).'),
name: NameSchema,
url: z.url().describe('URL of the remote MCP server.'),
+ description: McpServerDescriptionSchema,
auth: McpServerAuthSettingsSchema.optional().describe(
'Optional auth settings. Omit when the server needs no credentials.',
),
diff --git a/packages/server/tests/db/mcpServerStoreContractSuite.ts b/packages/server/tests/db/mcpServerStoreContractSuite.ts
index a8219db7b..7d0d28f9f 100644
--- a/packages/server/tests/db/mcpServerStoreContractSuite.ts
+++ b/packages/server/tests/db/mcpServerStoreContractSuite.ts
@@ -13,6 +13,7 @@ function manifest(overrides: Partial<McpServerManifest> = {}): McpServerManifest
type: 'remote',
name: 'linear',
url: 'https://mcp.linear.app/mcp',
+ description: 'Linear MCP server.',
auth: { type: 'dcr' },
...overrides,
};
diff --git a/packages/server/tests/db/postgres/token-store/contract.test.ts b/packages/server/tests/db/postgres/token-store/contract.test.ts
index af6ecc927..b3b642c8c 100644
--- a/packages/server/tests/db/postgres/token-store/contract.test.ts
+++ b/packages/server/tests/db/postgres/token-store/contract.test.ts
@@ -36,7 +36,12 @@ describePg('PostgresOAuthTokenStore (IOAuthTokenStore contract)', () => {
return {
store: new PostgresOAuthTokenStore(db),
async seedResource(id) {
- const manifest: McpServerManifest = { type: 'remote', name: id, url: 'https://mcp.example.com/sse' };
+ const manifest: McpServerManifest = {
+ type: 'remote',
+ name: id,
+ url: 'https://mcp.example.com/sse',
+ description: 'Test MCP server.',
+ };
await db
.insertInto('mcp_server')
.values({
diff --git a/packages/server/tests/db/sqlite/token-store/contract.test.ts b/packages/server/tests/db/sqlite/token-store/contract.test.ts
index cb4369653..fa27fe64f 100644
--- a/packages/server/tests/db/sqlite/token-store/contract.test.ts
+++ b/packages/server/tests/db/sqlite/token-store/contract.test.ts
@@ -24,7 +24,12 @@ describe('SqliteOAuthTokenStore (IOAuthTokenStore contract)', () => {
return {
store: new SqliteOAuthTokenStore(db),
async seedResource(id) {
- const manifest: McpServerManifest = { type: 'remote', name: id, url: 'https://mcp.example.com/sse' };
+ const manifest: McpServerManifest = {
+ type: 'remote',
+ name: id,
+ url: 'https://mcp.example.com/sse',
+ description: 'Test MCP server.',
+ };
await db
.insertInto('mcp_server')
.values({
diff --git a/packages/server/tests/unit/apis/mcpOAuth.test.ts b/packages/server/tests/unit/apis/mcpOAuth.test.ts
index 6e2a5eea6..0fad15ed3 100644
--- a/packages/server/tests/unit/apis/mcpOAuth.test.ts
+++ b/packages/server/tests/unit/apis/mcpOAuth.test.ts
@@ -121,7 +121,13 @@ describe('MCP OAuth authorize + callback', () => {
const put = await settingsRouter.request('/', {
method: 'PUT',
headers: { 'content-type': 'application/json' },
- body: JSON.stringify({ type: 'remote', name, url: MCP_URL, auth: { type: 'dcr' } }),
+ body: JSON.stringify({
+ type: 'remote',
+ name,
+ url: MCP_URL,
+ description: 'OAuth MCP server.',
+ auth: { type: 'dcr' },
+ }),
});
expect(put.status).toBe(200);
@@ -143,6 +149,7 @@ describe('MCP OAuth authorize + callback', () => {
type: 'remote',
name: 'oauth-mcp',
url: MCP_URL,
+ description: 'OAuth MCP server.',
auth: { type: 'dcr' },
}),
});
@@ -225,6 +232,7 @@ describe('MCP OAuth authorize + callback', () => {
type: 'remote',
name: 'oauth-mcp-scoped',
url: MCP_URL,
+ description: 'OAuth MCP server.',
auth: { type: 'dcr' },
}),
});
diff --git a/packages/server/tests/unit/apis/mcpServers.test.ts b/packages/server/tests/unit/apis/mcpServers.test.ts
index 889450291..a4cbe194d 100644
--- a/packages/server/tests/unit/apis/mcpServers.test.ts
+++ b/packages/server/tests/unit/apis/mcpServers.test.ts
@@ -17,12 +17,14 @@ const putBody = {
type: 'remote' as const,
name: 'deepwiki',
url: 'https://mcp.deepwiki.com/mcp',
+ description: 'DeepWiki MCP server.',
};
const putBodyWithDcr = {
type: 'remote' as const,
name: 'linear',
url: 'https://mcp.linear.app/mcp',
+ description: 'Linear MCP server.',
auth: { type: 'dcr' as const },
};
@@ -34,6 +36,7 @@ const putBodyWithHeaderAuth = {
type: 'remote' as const,
name: 'private-mcp',
url: 'https://mcp.example.com/mcp',
+ description: 'Private MCP server.',
auth: {
type: 'header' as const,
headers: { Authorization: HEADER_TOKEN },
@@ -166,6 +169,7 @@ describe('mcp-servers routers', () => {
type: 'remote' as const,
name: 'create-only-mcp',
url: 'https://mcp.example.com/create-only',
+ description: 'Create-only MCP server.',
};
const created = await settingsRouter.request('/', postInit(createBody));
expect(created.status).toBe(200);
@@ -210,6 +214,7 @@ describe('mcp-servers routers', () => {
type: 'remote' as const,
name: 'create-dcr-fail',
url: 'https://mcp.example.com/dcr-fail',
+ description: 'Create DCR fail MCP server.',
auth: { type: 'dcr' as const },
};
const response = await settingsRouter.request('/', postInit(createDcr));
@@ -659,6 +664,7 @@ describe('mcp-servers routers', () => {
type: 'remote',
name: 'failing-oauth-mcp',
url: mcpUrl,
+ description: 'Failing OAuth MCP server.',
auth: { type: 'dcr' },
}),
);
@@ -723,6 +729,7 @@ describe('mcp-servers routers', () => {
type: 'remote',
name: 'oauth-mcp',
url: mcpUrl,
+ description: 'OAuth MCP server.',
auth: { type: 'dcr' },
}),
);
diff --git a/packages/server/tests/unit/runtime/getMcpConnection.test.ts b/packages/server/tests/unit/runtime/getMcpConnection.test.ts
index 81bb02547..5c5ee5be2 100644
--- a/packages/server/tests/unit/runtime/getMcpConnection.test.ts
+++ b/packages/server/tests/unit/runtime/getMcpConnection.test.ts
@@ -70,6 +70,7 @@ describe('getMcpConnection', () => {
type: 'remote',
name: 'oauth-mcp',
url: mcpUrl,
+ description: 'OAuth MCP server.',
auth: { type: 'dcr' },
},
});
@@ -119,6 +120,7 @@ describe('getMcpConnection', () => {
type: 'remote',
name: 'tokened-mcp',
url: 'https://mcp.tokened.example/mcp',
+ description: 'Tokened MCP server.',
auth: { type: 'dcr' },
},
});
@@ -158,6 +160,7 @@ describe('getMcpConnection', () => {
type: 'remote',
name: 'open-mcp',
url: 'https://mcp.open.example/mcp',
+ description: 'Open MCP server.',
},
});
@@ -186,6 +189,7 @@ describe('getMcpConnection', () => {
type: 'remote',
name: 'header-mcp',
url: 'https://mcp.header.example/mcp',
+ description: 'Header MCP server.',
auth: { type: 'header', headers: { Authorization: 'Bearer static-token' } },
},
});
diff --git a/packages/trueforge-ui-sdk/src/plugins/trueforge-agent-server-adapter/catalogs/connectorCatalog.ts b/packages/trueforge-ui-sdk/src/plugins/trueforge-agent-server-adapter/catalogs/connectorCatalog.ts
index 9e70ea822..fad72515a 100644
--- a/packages/trueforge-ui-sdk/src/plugins/trueforge-agent-server-adapter/catalogs/connectorCatalog.ts
+++ b/packages/trueforge-ui-sdk/src/plugins/trueforge-agent-server-adapter/catalogs/connectorCatalog.ts
@@ -58,6 +58,7 @@ export function toUiCatalogEntry(server: TrueForgeApi.CatalogMcpServer): UiConne
id: server.name,
name: server.name,
url: server.url,
+ description: server.description,
...(server.logo === undefined ? {} : { logo: server.logo }),
auth: toUiAuthPublic(server.auth),
};
@@ -74,7 +75,7 @@ export function toUiConnector(server: TrueForgeApi.ConfiguredMcpServer): UiConne
return {
id: server.name,
name: server.name,
- description: server.url,
+ description: server.description,
url: server.url,
auth,
requiresAuth: server.authStatus.status === 'auth_required',
@@ -98,14 +99,22 @@ export function toUiConnectorFromReadEntry(server: TrueForgeApi.McpServerReadEnt
export interface HarnessMcpUpsert {
name: string;
url: string;
+ description: string;
auth?: TrueForgeApi.ConfiguredMcpServerAuth;
}
-export function toHarnessManifest(req: { name: string; url: string; auth: ConnectorAuth }): HarnessMcpUpsert {
+export function toHarnessManifest(req: {
+ name: string;
+ url: string;
+ auth: ConnectorAuth;
+ description?: string;
+}): HarnessMcpUpsert {
const auth = toHarnessAuth(req.auth);
+ const trimmed = req.description?.trim();
return {
name: req.name,
url: req.url,
+ description: trimmed !== undefined && trimmed !== '' ? trimmed : `${req.name} MCP server`,
...(auth === undefined ? {} : { auth }),
};
}
@@ -188,12 +197,29 @@ export function createConnectorCatalog(
},
createConnector: async req => {
const auth = await resolveWriteAuth({ auth: req.auth });
- const body = await client.settings.mcpServers.create(toHarnessManifest({ name: req.name, url: req.url, auth }));
+ const catalog = await client.catalog.mcpServers.list();
+ const preset = catalog.data.find(server => server.name === req.name);
+ const body = await client.settings.mcpServers.create(
+ toHarnessManifest({
+ name: req.name,
+ url: req.url,
+ auth,
+ description: preset?.description,
+ }),
+ );
return toUiConnector(body.data);
},
updateConnector: async req => {
+ const existing = await getConfigured(req.id);
const auth = await resolveWriteAuth({ id: req.id, auth: req.auth });
- const body = await client.settings.mcpServers.upsert(toHarnessManifest({ name: req.id, url: req.url, auth }));
+ const body = await client.settings.mcpServers.upsert(
+ toHarnessManifest({
+ name: req.id,
+ url: req.url,
+ auth,
+ description: existing.description,
+ }),
+ );
return toUiConnector(body.data);
},
authenticateConnector: async req => {
diff --git a/packages/trueforge-ui-sdk/test/plugins/trueforge-agent-server-adapter/catalogs/connectorCatalog.test.ts b/packages/trueforge-ui-sdk/test/plugins/trueforge-agent-server-adapter/catalogs/connectorCatalog.test.ts
index 7ae9d183f..d83346ee8 100644
--- a/packages/trueforge-ui-sdk/test/plugins/trueforge-agent-server-adapter/catalogs/connectorCatalog.test.ts
+++ b/packages/trueforge-ui-sdk/test/plugins/trueforge-agent-server-adapter/catalogs/connectorCatalog.test.ts
@@ -44,12 +44,14 @@ describe('connectorCatalog mappers', () => {
type: 'remote',
name: 'linear',
url: 'https://mcp.linear.app/mcp',
+ description: 'Linear MCP server.',
auth: { type: 'dcr' },
}),
{
id: 'linear',
name: 'linear',
url: 'https://mcp.linear.app/mcp',
+ description: 'Linear MCP server.',
auth: { type: 'dcr' },
},
);
@@ -61,12 +63,13 @@ describe('connectorCatalog mappers', () => {
type: 'remote',
name: 'deepwiki',
url: 'https://mcp.deepwiki.com/mcp',
+ description: 'DeepWiki MCP server.',
authStatus: { status: 'not_required' },
}),
{
id: 'deepwiki',
name: 'deepwiki',
- description: 'https://mcp.deepwiki.com/mcp',
+ description: 'DeepWiki MCP server.',
url: 'https://mcp.deepwiki.com/mcp',
auth: { type: 'none' },
requiresAuth: false,
@@ -80,6 +83,7 @@ describe('connectorCatalog mappers', () => {
type: 'remote',
name: 'linear',
url: 'https://mcp.linear.app/mcp',
+ description: 'Linear MCP server.',
auth: { type: 'dcr' },
authStatus: { status: 'auth_required' },
});
@@ -90,6 +94,7 @@ describe('connectorCatalog mappers', () => {
type: 'remote',
name: 'linear',
url: 'https://mcp.linear.app/mcp',
+ description: 'Linear MCP server.',
auth: { type: 'dcr' },
authStatus: { status: 'authenticated' },
});
@@ -141,6 +146,7 @@ describe('connectorCatalog mappers', () => {
{
name: 'linear',
url: 'https://mcp.linear.app/mcp',
+ description: 'linear MCP server',
auth: { type: 'dcr' },
},
);
@@ -153,6 +159,35 @@ describe('connectorCatalog mappers', () => {
{
name: 'custom-mcp',
url: 'https://example.com/mcp',
+ description: 'custom-mcp MCP server',
+ },
+ );
+ assert.deepEqual(
+ toHarnessManifest({
+ name: 'linear',
+ url: 'https://mcp.linear.app/mcp',
+ auth: { type: 'dcr' },
+ description: 'Linear MCP server.',
+ }),
+ {
+ name: 'linear',
+ url: 'https://mcp.linear.app/mcp',
+ description: 'Linear MCP server.',
+ auth: { type: 'dcr' },
+ },
+ );
+ assert.deepEqual(
+ toHarnessManifest({
+ name: 'linear',
+ url: 'https://mcp.linear.app/mcp',
+ auth: { type: 'dcr' },
+ description: ' ',
+ }),
+ {
+ name: 'linear',
+ url: 'https://mcp.linear.app/mcp',
+ description: 'linear MCP server',
+ auth: { type: 'dcr' },
},
);
});