get_mcp_integration_metadata

Instructions

Implementation Reference

• src/tools/mcp-integrations.tools.ts:361-381 (handler)

  Tool handler for 'get_mcp_integration_metadata'. Calls service.mcpIntegrations.getMcpIntegrationMetadata(id) and formats the result with formatMcpIntegrationMetadata().

  server.tool(
  	"get_mcp_integration_metadata",
  	"Retrieve the external MCP server's self-reported metadata for an integration. Returns name, version, protocol, capability flags, and sync status; use get_mcp_integration for the Portkey-side connection config.",
  	MCP_INTEGRATIONS_TOOL_SCHEMAS.getMcpIntegrationMetadata,
  	async (params) => {
  		const metadata = await service.mcpIntegrations.getMcpIntegrationMetadata(
  			params.id,
  		);
  		return {
  			content: [
  				{
  					type: "text",
  					text: JSON.stringify(
  						formatMcpIntegrationMetadata(metadata),
  						null,
  						2,
  					),
  				},
  			],
  		};
  	},

• src/tools/mcp-integrations.tools.ts:86-88 (schema)

  Zod schema for getMcpIntegrationMetadata tool input: requires 'id' (string) describing the MCP integration ID or slug.

  getMcpIntegrationMetadata: {
  	id: z.string().describe("The MCP integration ID or slug"),
  },

• src/tools/mcp-integrations.tools.ts:175-203 (helper)

  Helper function formatMcpIntegrationMetadata that transforms raw McpIntegrationMetadata into a formatted response object with derived icon_count.

  function formatMcpIntegrationMetadata(metadata: McpIntegrationMetadata): {
  	server_name: string | null;
  	server_version: string | null;
  	title: string | null;
  	description: string | null;
  	website_url: string | null;
  	protocol_version: string | null;
  	icon_count: number;
  	capability_flags: unknown;
  	instructions: string | null;
  	sync_status: "pending" | "synced" | "error";
  	last_synced_at: string | null;
  	sync_error: string | null;
  } {
  	return {
  		server_name: metadata.server_name,
  		server_version: metadata.server_version,
  		title: metadata.title,
  		description: metadata.description,
  		website_url: metadata.website_url,
  		protocol_version: metadata.protocol_version,
  		icon_count: Array.isArray(metadata.icons) ? metadata.icons.length : 0,
  		capability_flags: metadata.capability_flags,
  		instructions: metadata.instructions,
  		sync_status: metadata.sync_status,
  		last_synced_at: metadata.last_synced_at,
  		sync_error: metadata.sync_error,
  	};
  }

• src/tools/mcp-integrations.tools.ts:217-489 (registration)

  Function registerMcpIntegrationsTools registers all MCP integration tools including 'get_mcp_integration_metadata' via server.tool().

  export function registerMcpIntegrationsTools(
  	server: McpServer,
  	service: PortkeyService,
  ): void {
  	server.tool(
  		"list_mcp_integrations",
  		"List MCP integrations in the organization. Returns paginated integration records plus total and has_more for discovering integration IDs; use get_mcp_integration for one integration's full Portkey-side config and list_mcp_servers for the servers under an integration.",
  		MCP_INTEGRATIONS_TOOL_SCHEMAS.listMcpIntegrations,
  		async (params) => {
  			const result = await service.mcpIntegrations.listMcpIntegrations(params);
  			return {
  				content: [
  					{
  						type: "text",
  						text: JSON.stringify(
  							{
  								total: result.total,
  								has_more: result.has_more,
  								integrations: result.data.map(formatMcpIntegration),
  							},
  							null,
  							2,
  						),
  					},
  				],
  			};
  		},
  	);
  
  	server.tool(
  		"create_mcp_integration",
  		"Create an MCP integration from an external server URL. Registers the Portkey-side connection and returns the new id and slug; if auth_type is headers, custom_headers are required, and you usually follow with create_mcp_server and capability updates.",
  		MCP_INTEGRATIONS_TOOL_SCHEMAS.createMcpIntegration,
  		async (params) => {
  			if (
  				params.auth_type === "headers" &&
  				(!params.custom_headers ||
  					Object.keys(params.custom_headers).length === 0)
  			) {
  				return {
  					content: [
  						{
  							type: "text" as const,
  							text: "Error: custom_headers must be provided when auth_type is 'headers'",
  						},
  					],
  					isError: true,
  				};
  			}
  			const { custom_headers, ...rest } = params;
  			const result = await service.mcpIntegrations.createMcpIntegration({
  				...rest,
  				...(custom_headers ? { configurations: { custom_headers } } : {}),
  			});
  			return {
  				content: [
  					{
  						type: "text",
  						text: JSON.stringify(
  							{
  								message: `Successfully created MCP integration "${params.name}"`,
  								id: result.id,
  								slug: result.slug,
  							},
  							null,
  							2,
  						),
  					},
  				],
  			};
  		},
  	);
  
  	server.tool(
  		"get_mcp_integration",
  		"Retrieve one MCP integration by id or slug. Returns the full Portkey-side config, including auth type, transport, and masked configuration keys; use get_mcp_integration_metadata for the server's self-reported metadata.",
  		MCP_INTEGRATIONS_TOOL_SCHEMAS.getMcpIntegration,
  		async (params) => {
  			const integration = await service.mcpIntegrations.getMcpIntegration(
  				params.id,
  			);
  			return {
  				content: [
  					{
  						type: "text",
  						text: JSON.stringify(formatMcpIntegration(integration), null, 2),
  					},
  				],
  			};
  		},
  	);
  
  	server.tool(
  		"update_mcp_integration",
  		"Update an MCP integration's name, description, URL, auth, or transport. Changes apply immediately and altering url or auth_type can break connected clients; use update_mcp_server when you only need to rename or re-describe a server.",
  		MCP_INTEGRATIONS_TOOL_SCHEMAS.updateMcpIntegration,
  		async (params) => {
  			const { id, custom_headers, ...rest } = params;
  			await service.mcpIntegrations.updateMcpIntegration(id, {
  				...rest,
  				...(custom_headers ? { configurations: { custom_headers } } : {}),
  			});
  			return {
  				content: [
  					{
  						type: "text",
  						text: JSON.stringify(
  							{
  								message: `Successfully updated MCP integration "${id}"`,
  								success: true,
  							},
  							null,
  							2,
  						),
  					},
  				],
  			};
  		},
  	);
  
  	server.tool(
  		"delete_mcp_integration",
  		"Delete an MCP integration and all servers beneath it. This is irreversible, removes connected access immediately, and should only be used after confirming nothing depends on the integration.",
  		MCP_INTEGRATIONS_TOOL_SCHEMAS.deleteMcpIntegration,
  		async (params) => {
  			await service.mcpIntegrations.deleteMcpIntegration(params.id);
  			return {
  				content: [
  					{
  						type: "text",
  						text: JSON.stringify(
  							{
  								message: `Successfully deleted MCP integration "${params.id}"`,
  								success: true,
  							},
  							null,
  							2,
  						),
  					},
  				],
  			};
  		},
  	);
  
  	server.tool(
  		"get_mcp_integration_metadata",
  		"Retrieve the external MCP server's self-reported metadata for an integration. Returns name, version, protocol, capability flags, and sync status; use get_mcp_integration for the Portkey-side connection config.",
  		MCP_INTEGRATIONS_TOOL_SCHEMAS.getMcpIntegrationMetadata,
  		async (params) => {
  			const metadata = await service.mcpIntegrations.getMcpIntegrationMetadata(
  				params.id,
  			);
  			return {
  				content: [
  					{
  						type: "text",
  						text: JSON.stringify(
  							formatMcpIntegrationMetadata(metadata),
  							null,
  							2,
  						),
  					},
  				],
  			};
  		},
  	);
  
  	server.tool(
  		"list_mcp_integration_capabilities",
  		"List capabilities exposed by the external MCP server for an integration. Returns total plus enabled-state entries so you can decide what to toggle; use before update_mcp_integration_capabilities when you need to compare the current surface.",
  		MCP_INTEGRATIONS_TOOL_SCHEMAS.listMcpIntegrationCapabilities,
  		async (params) => {
  			const result =
  				await service.mcpIntegrations.listMcpIntegrationCapabilities(params.id);
  			return {
  				content: [
  					{
  						type: "text",
  						text: JSON.stringify(
  							{ total: result.total, capabilities: result.data },
  							null,
  							2,
  						),
  					},
  				],
  			};
  		},
  	);
  
  	server.tool(
  		"update_mcp_integration_capabilities",
  		"Bulk enable or disable capabilities on an MCP integration. Changes take effect immediately for connected users and hide or expose the selected tools, resources, and prompts; use list_mcp_integration_capabilities first if you need the current state.",
  		MCP_INTEGRATIONS_TOOL_SCHEMAS.updateMcpIntegrationCapabilities,
  		async (params) => {
  			await service.mcpIntegrations.updateMcpIntegrationCapabilities(
  				params.id,
  				{
  					capabilities: params.capabilities,
  				},
  			);
  			return {
  				content: [
  					{
  						type: "text",
  						text: JSON.stringify(
  							{
  								message: `Successfully updated capabilities for MCP integration "${params.id}"`,
  								success: true,
  							},
  							null,
  							2,
  						),
  					},
  				],
  			};
  		},
  	);
  
  	server.tool(
  		"list_mcp_integration_workspaces",
  		"List which workspaces can access an MCP integration. Returns the global access mode plus per-workspace enablement for audit or permission review; use before update_mcp_integration_workspaces.",
  		MCP_INTEGRATIONS_TOOL_SCHEMAS.listMcpIntegrationWorkspaces,
  		async (params) => {
  			const result = await service.mcpIntegrations.listMcpIntegrationWorkspaces(
  				params.id,
  			);
  			return {
  				content: [
  					{
  						type: "text",
  						text: JSON.stringify(
  							{
  								global_workspace_access: result.global_workspace_access,
  								workspace_count: result.workspaces.length,
  								workspaces: result.workspaces.map(
  									formatMcpIntegrationWorkspace,
  								),
  							},
  							null,
  							2,
  						),
  					},
  				],
  			};
  		},
  	);
  
  	server.tool(
  		"update_mcp_integration_workspaces",
  		"Grant or revoke workspace access to an MCP integration in bulk. Changes take effect immediately for all users in the selected workspaces; use list_mcp_integration_workspaces first to review the current access state.",
  		MCP_INTEGRATIONS_TOOL_SCHEMAS.updateMcpIntegrationWorkspaces,
  		async (params) => {
  			await service.mcpIntegrations.updateMcpIntegrationWorkspaces(params.id, {
  				workspaces: params.workspaces,
  			});
  			return {
  				content: [
  					{
  						type: "text",
  						text: JSON.stringify(
  							{
  								message: `Successfully updated workspace access for MCP integration "${params.id}"`,
  								success: true,
  							},
  							null,
  							2,
  						),
  					},
  				],
  			};
  		},
  	);
  }

• src/services/mcp-integrations.service.ts:176-180 (handler)

  Service method getMcpIntegrationMetadata that makes a GET request to /mcp-integrations/{id}/metadata returning McpIntegrationMetadata.

  async getMcpIntegrationMetadata(id: string): Promise<McpIntegrationMetadata> {
  	return this.get<McpIntegrationMetadata>(
  		`/mcp-integrations/${this.encodePathSegment(id)}/metadata`,
  	);
  }