Register‑ShpMcpServer

SYNOPSIS

Attaches an MCP (Model Context Protocol) server so its tools are offered to the model.

SYNTAX

Command (Default)

Register-ShpMcpServer [-Name] <String> -Command <String> [-Argument <String[]>] [-WorkingDirectory <String>]
 [-Environment <Hashtable>] [-ToolName <String[]>] [-MaxTool <Int32>] [-ConnectTimeoutSec <Int32>]
 [-RequestTimeoutSec <Int32>] [-Force] [-PassThru] [-WhatIf] [-Confirm]
 [<CommonParameters>]

Path

Register-ShpMcpServer [[-Name] <String>] -Path <String> [-ToolName <String[]>] [-MaxTool <Int32>]
 [-ConnectTimeoutSec <Int32>] [-RequestTimeoutSec <Int32>] [-Force] [-PassThru]
 [-WhatIf] [-Confirm] [<CommonParameters>]

Url

Register-ShpMcpServer [-Name] <String> -Url <String> [-AllowLoopbackHttp] [-Header <Hashtable>]
 [-CredentialCallback <ScriptBlock>] [-MaxResponseBytes <Int32>] [-MaxStreamEvent <Int32>]
 [-MaxRedirect <Int32>] [-Transport <ScriptBlock>] [-ToolName <String[]>] [-MaxTool <Int32>]
 [-ConnectTimeoutSec <Int32>] [-RequestTimeoutSec <Int32>] [-Force] [-PassThru]
 [-WhatIf] [-Confirm] [<CommonParameters>]

DESCRIPTION

Starts a stdio MCP server, negotiates the protocol with it, captures its tool list, and adds those tools to the ones Invoke-Shp offers the model alongside its built-ins and any user-defined tools.

Attaching is always an explicit act. Nothing scans the working directory, .vscode or a user profile for a configuration file, because a configuration file is a command line and a command line is arbitrary code. -Path reads a file you name and nothing else.

The server is started here rather than lazily inside a Turn, so a failure to start is a failure of this command, with the server's own standard-error output in the message, instead of a quietly degraded Turn. The process then stays attached across Invoke-Shp calls until you unregister it or the session ends.

The tool list is captured ONCE and offered unchanged for the life of the attachment. This client opens no subscription stream, so it receives no notifications/tools/list_changed and a server cannot add or alter tools after you approved them. Refreshing is an explicit -Force re-registration.

Both protocol eras are supported. Revision 2026-07-28 removed the initialize handshake in favour of per-request metadata, while nearly every server in the field still expects the handshake, so the client probes with server/discover and falls back.

SECURITY. An MCP server is a third-party process running with your privileges, and there is no sandbox. Its tool names and descriptions are untrusted input that the model reads on every round-trip, and its results are untrusted content. Set-ShpToolPolicy DOES gate an MCP call when the policy covers the Mcp kind: a call is matched on the alias and tool that will actually dispatch - Mcp(files/read_text_file) - and is deny-by-default like every covered kind. A policy written before that kind existed does not cover it and leaves MCP calls ungated, which is what keeps an older policy working unchanged. Gating is not containment either way, so use -ToolName to attach only the tools you actually need.

EXAMPLES

EXAMPLE 1

Register-ShpMcpServer -Name files -Command npx -Argument '-y','@modelcontextprotocol/server-filesystem','C:\work'

Attaches a filesystem server; its tools appear as mcp_files_*.

EXAMPLE 2

Register-ShpMcpServer -Name gh -Command npx -Argument '-y','@some/mcp-github' -Environment @{ GITHUB_TOKEN = $token } -ToolName 'search_issues','get_issue'

Passes one credential to the server and offers only two of its tools.

EXAMPLE 3

Register-ShpMcpServer -Path .\.vscode\mcp.json

Attaches every stdio server defined in a configuration file you named.

EXAMPLE 4

Register-ShpMcpServer -Name docs -Url https://mcp.example.com/mcp -Header @{ 'X-Api-Key' = $key }

Attaches a remote server over Streamable HTTP, sending only that header.

PARAMETERS

-AllowLoopbackHttp

Permit a loopback endpoint, including over plain http. Reaching a local development server is legitimate and has to be asked for; the opt-in cannot be turned into general cleartext reach, because http to anything that is not loopback is still refused.

Type: SwitchParameter
Parameter Sets: Url
Aliases:

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

-Argument

Arguments for the command, one array element per argument.

Type: String[]
Parameter Sets: Command
Aliases:

Required: False
Position: Named
Default value: @()
Accept pipeline input: False
Accept wildcard characters: False

-Command

The executable to run, for example 'npx' or 'python'.

Type: String
Parameter Sets: Command
Aliases:

Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-ConnectTimeoutSec

How long to wait for the protocol probe and handshake. Default 10.

Type: Int32
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: 0
Accept pipeline input: False
Accept wildcard characters: False

-CredentialCallback

A scriptblock returning a bearer token already bound to this resource and its scopes. Invoked per request and never stored, written to disk or put on the server record. This is the ONLY authorization this client performs: it cannot run an interactive authorization-code flow and will not guess at a machine flow, so a 401 is reported with its challenge rather than answered with whatever token is in reach.

Type: ScriptBlock
Parameter Sets: Url
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Environment

Environment variables to give the server. The child does NOT inherit your environment block: it starts from a minimal base and receives exactly what you name here, so an ambient $env: credential is not handed to somebody else's process.

Type: Hashtable
Parameter Sets: Command
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Force

Replace an existing attachment with the same name, stopping the old process first. This is also how a tool list is deliberately refreshed.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

-Header

Headers sent with every request to this remote server, and nothing else is. No ambient credential, proxy credential or cookie travels with a request - a third-party endpoint is not handed your network identity because it asked for it.

Type: Hashtable
Parameter Sets: Url
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-MaxRedirect

Ceiling on the redirect chain of one remote request.

Type: Int32
Parameter Sets: Url
Aliases:

Required: False
Position: Named
Default value: -1
Accept pipeline input: False
Accept wildcard characters: False

-MaxResponseBytes

Ceiling on a remote response body. A larger reply is refused rather than buffered.

Type: Int32
Parameter Sets: Url
Aliases:

Required: False
Position: Named
Default value: 0
Accept pipeline input: False
Accept wildcard characters: False

-MaxStreamEvent

Ceiling on how many server-sent events are read while awaiting one response.

Type: Int32
Parameter Sets: Url
Aliases:

Required: False
Position: Named
Default value: 0
Accept pipeline input: False
Accept wildcard characters: False

-MaxTool

Maximum number of tools to accept from the server. Default 64. Every tool schema is re-sent and billed on every round-trip of a Turn.

Type: Int32
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: 0
Accept pipeline input: False
Accept wildcard characters: False

-Name

The alias for this server. It namespaces the server's tools as mcp__, so two servers offering a 'search' tool cannot collide. Mandatory when starting a command; an optional filter when reading a configuration file.

Type: String
Parameter Sets: Command, Url
Aliases:

Required: True
Position: 1
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

Type: String
Parameter Sets: Path
Aliases:

Required: False
Position: 1
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-PassThru

Return the record of each server that was attached.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

-Path

Path to an MCP configuration file to read. Both the VS Code shape ({ "servers": ... }) and the Claude Desktop shape ({ "mcpServers": ... }) are accepted.

Type: String
Parameter Sets: Path
Aliases:

Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-RequestTimeoutSec

How long to wait for any later request, including a tool call. Default 30.

Type: Int32
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: 0
Accept pipeline input: False
Accept wildcard characters: False

-ToolName

Offer only these tools from the server. Supports wildcards. This is the one place where an MCP server's reach can honestly be reduced.

Type: String[]
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: True

-Transport

A caller-owned transport for the remote channel, used instead of the built-in one. Intended for testing a server contract without a socket.

Type: ScriptBlock
Parameter Sets: Url
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Url

Attach a REMOTE server over Streamable HTTP instead of starting a local process. HTTPS is required and the endpoint is validated before a byte is sent: no embedded credentials, no fragment, and every address it resolves to must be publicly routable, so a model cannot be steered into attaching the host's own metadata service or an intranet admin interface. The approved address set is PINNED, and every later redirect is checked against it, so the endpoint cannot be moved by DNS after you approved it. When a Tool policy covers the Url kind, the endpoint must also pass its rules - an address this session may not fetch is not one it may attach a server from.

Type: String
Parameter Sets: Url
Aliases:

Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-WorkingDirectory

Directory to start the server in. Defaults to the current location.

Type: String
Parameter Sets: Command
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Confirm

Prompts you for confirmation before running the cmdlet.

Type: SwitchParameter
Parameter Sets: (All)
Aliases: cf

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-WhatIf

Shows what would happen if the cmdlet runs. The cmdlet is not run.

Type: SwitchParameter
Parameter Sets: (All)
Aliases: wi

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

CommonParameters

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.

INPUTS

OUTPUTS

None by default; the server record when -PassThru is used.

NOTES

RELATED LINKS

Get-ShpMcpServer

Unregister-ShpMcpServer

Invoke-Shp