get_mcp_server
Read-onlyIdempotent
Retrieve an MCP server's details including parent integration, status, and creation time by providing its ID or slug. Get the server record when you need server metadata, not the integration config.
Instructions
Retrieve one MCP server by id or slug. Returns server details including the parent integration, status, and created time; use get_mcp_server when you need the server record rather than the integration config.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The MCP server ID or slug to retrieve |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ok | Yes | Whether the tool call succeeded and returned structured data | |
| data | No | Structured success payload when ok is true | |
| error | No | Structured error payload when ok is false |
Implementation Reference
- src/tools/mcp-servers.tools.ts:200-214 (handler)Handler function that executes the get_mcp_server tool logic. Calls the service layer's getMcpServer with the provided id and formats the result.
server.tool( "get_mcp_server", "Retrieve one MCP server by id or slug. Returns server details including the parent integration, status, and created time; use get_mcp_server when you need the server record rather than the integration config.", MCP_SERVERS_TOOL_SCHEMAS.getMcpServer, async (params) => { const mcpServer = await service.mcpServers.getMcpServer(params.id); return { content: [ { type: "text", text: JSON.stringify(formatMcpServer(mcpServer), null, 2), }, ], }; }, - src/tools/mcp-servers.tools.ts:40-42 (schema)Zod schema defining the input for get_mcp_server: a single required 'id' string parameter.
getMcpServer: { id: z.string().describe("The MCP server ID or slug to retrieve"), }, - src/tools/mcp-servers.tools.ts:147-384 (registration)Registration function that registers all MCP server tools including get_mcp_server via server.tool().
export function registerMcpServersTools( server: McpServer, service: PortkeyService, ): void { server.tool( "list_mcp_servers", "List MCP servers in the organization. Returns paginated server records plus total for discovering server IDs; use get_mcp_server for one server's details and list_mcp_integrations for the parent integration.", MCP_SERVERS_TOOL_SCHEMAS.listMcpServers, async (params) => { const result = await service.mcpServers.listMcpServers(params); return { content: [ { type: "text", text: JSON.stringify( { total: result.total, servers: result.data.map(formatMcpServer), }, null, 2, ), }, ], }; }, ); server.tool( "create_mcp_server", "Create an MCP server under an existing integration. Registers the server and returns the new id and slug; use list_mcp_integrations first to find the parent integration, then capabilities or access tools to configure it.", MCP_SERVERS_TOOL_SCHEMAS.createMcpServer, async (params) => { const result = await service.mcpServers.createMcpServer(params); return { content: [ { type: "text", text: JSON.stringify( { message: `Successfully created MCP server "${params.name}"`, id: result.id, slug: result.slug, }, null, 2, ), }, ], }; }, ); server.tool( "get_mcp_server", "Retrieve one MCP server by id or slug. Returns server details including the parent integration, status, and created time; use get_mcp_server when you need the server record rather than the integration config.", MCP_SERVERS_TOOL_SCHEMAS.getMcpServer, async (params) => { const mcpServer = await service.mcpServers.getMcpServer(params.id); return { content: [ { type: "text", text: JSON.stringify(formatMcpServer(mcpServer), null, 2), }, ], }; }, ); server.tool( "update_mcp_server", "Update an MCP server's name or description. Changes apply immediately, but URL and auth live on the parent integration, so use update_mcp_integration for those fields.", MCP_SERVERS_TOOL_SCHEMAS.updateMcpServer, async (params) => { const { id, ...data } = params; await service.mcpServers.updateMcpServer(id, data); return { content: [ { type: "text", text: JSON.stringify( { message: `Successfully updated MCP server "${id}"`, success: true, }, null, 2, ), }, ], }; }, ); server.tool( "delete_mcp_server", "Delete an MCP server instance. This is irreversible, removes connected users' access immediately, and should be used only after confirming no workflows depend on the server.", MCP_SERVERS_TOOL_SCHEMAS.deleteMcpServer, async (params) => { await service.mcpServers.deleteMcpServer(params.id); return { content: [ { type: "text", text: JSON.stringify( { message: `Successfully deleted MCP server "${params.id}"`, success: true, }, null, 2, ), }, ], }; }, ); server.tool( "test_mcp_server", "Test connectivity to an MCP server. Sends a live check and returns success, response time, HTTP status, and any error; use this before changing configuration or when diagnosing reachability.", MCP_SERVERS_TOOL_SCHEMAS.testMcpServer, async (params) => { const result = await service.mcpServers.testMcpServer(params.id); return { content: [ { type: "text", text: JSON.stringify(formatMcpServerTest(result), null, 2), }, ], }; }, ); server.tool( "list_mcp_server_capabilities", "List capabilities exposed by an MCP server instance. Returns total plus the current tool, resource, and prompt surface; use this instead of the integration-level capability list when you need server-specific exposure.", MCP_SERVERS_TOOL_SCHEMAS.listMcpServerCapabilities, async (params) => { const result = await service.mcpServers.listMcpServerCapabilities( params.id, ); return { content: [ { type: "text", text: JSON.stringify( { total: result.total, capabilities: result.data }, null, 2, ), }, ], }; }, ); server.tool( "update_mcp_server_capabilities", "Enable or disable capabilities on an MCP server. Changes take effect immediately and override the integration-level settings for this server; use list_mcp_server_capabilities first to inspect the current surface.", MCP_SERVERS_TOOL_SCHEMAS.updateMcpServerCapabilities, async (params) => { await service.mcpServers.updateMcpServerCapabilities(params.id, { capabilities: params.capabilities, }); return { content: [ { type: "text", text: JSON.stringify( { message: `Successfully updated capabilities for MCP server "${params.id}"`, success: true, }, null, 2, ), }, ], }; }, ); server.tool( "list_mcp_server_user_access", "List per-user access for an MCP server. Returns the default access mode, override flags, and connection status so you can audit who can use it; use before update_mcp_server_user_access.", MCP_SERVERS_TOOL_SCHEMAS.listMcpServerUserAccess, async (params) => { const result = await service.mcpServers.listMcpServerUserAccess( params.id, ); return { content: [ { type: "text", text: JSON.stringify( { default_user_access: result.default_user_access, total: result.total, users: result.data.map(formatMcpServerUserAccess), }, null, 2, ), }, ], }; }, ); server.tool( "update_mcp_server_user_access", "Grant or revoke individual user access to an MCP server. Changes take effect immediately and override the default access setting for the selected users; use list_mcp_server_user_access first if you need the current state.", MCP_SERVERS_TOOL_SCHEMAS.updateMcpServerUserAccess, async (params) => { await service.mcpServers.updateMcpServerUserAccess(params.id, { user_access: params.users, }); return { content: [ { type: "text", text: JSON.stringify( { message: `Successfully updated user access for MCP server "${params.id}"`, success: true, }, null, 2, ), }, ], }; }, ); } - Helper function to format an MCP server object into the shape returned by the tool handler.
function formatMcpServer(server: PortkeyMcpServer): { id: string; name: string; slug: string; description?: string | null; mcp_integration_id: string; status: "active" | "archived"; created_at: string; } { return { id: server.id, name: server.name, slug: server.slug, description: server.description, mcp_integration_id: server.mcp_integration_id, status: server.status, created_at: server.created_at, }; } - Service layer method that makes a GET request to /mcp-servers/{id} to fetch the MCP server details from the API.
async getMcpServer(id: string): Promise<McpServer> { return this.get<McpServer>(`/mcp-servers/${this.encodePathSegment(id)}`); }