Microsoft Announces Type Server Protocol, Extension of Language Server Protocol

The Type Server Protocol (TSP) is a JSON-RPC protocol for asking a type server for Python analysis data. A type server maintains the type-analysis state for a workspace and answers requests for the protocol version, snapshots, Python search paths, import resolution, and type queries (computed, declared, and expected types).

The protocol uses Language Server Protocol (LSP) data shapes and conventions where they are useful, such as Position and Range, and it represents URIs as strings the same way LSP does. TSP methods use the typeServer/ prefix.

The protocol artifacts in this folder are the authoritative definitions:

TSP uses semantic version strings for client/server compatibility checks. While the protocol is in the 0.x line, minor version changes may be breaking. Patch version changes remain backward compatible within the same minor line.

A client starts a type server and communicates with it over the main JSON-RPC connection using a transport the server supports, such as stdio or Node IPC. When using stdio, stdout must be reserved for JSON-RPC protocol messages.

A type server is expected to receive enough workspace and document state to answer the TSP requests it supports. Clients commonly use normal LSP initialization and document synchronization for this state, then send typeServer/* requests on the same JSON-RPC connection.

TSP also supports optional extra read-only connections. The original connection remains the main connection and owns initialization, workspace state, document synchronization, state-changing notifications, and connection control. Extra connections are opened only after client and server negotiate support during initialization.

Multi-connection mode is an optional performance feature. It lets a client open additional local channels to the same type server for read-only TSP requests, while the main connection continues to own the mutable workspace state.

Clients should use multi-connection mode only when they can benefit from concurrent read-only work, such as high-volume type queries or background workers that should not block the main JSON-RPC connection. A server must still work correctly in single-connection mode. Multi-connection support must not be required for protocol correctness.

Multi-connection support is negotiated through the normal LSP initialize request and response. A client that can open extra TSP channels advertises the supported transport kinds under capabilities.experimental.typeServerMultiConnection:

{ "capabilities": { "experimental": { "typeServerMultiConnection": { "supportedTransports": ["ipc"] } } } }

A server that can serve extra TSP channels returns the same capability shape in the initialize result:

{ "capabilities": { "experimental": { "typeServerMultiConnection": { "supportedTransports": ["ipc"] } } } }

Multi-connection mode is enabled only when both sides advertise typeServerMultiConnection and the two supportedTransports lists have at least one transport in common. If either side omits the capability, or if there is no common transport, the session remains single-connection and the client must not send typeServer/connection.

The currently supported built-in transport kind for extra connections is ipc. This negotiation is separate from the main connection, which can use stdio or Node IPC.

After initialization and transport negotiation, the client opens an extra channel by sending typeServer/connection on the main connection:

{ "type": "open", "kind": "ipc", "args": ["<ipc-endpoint>"] }

For ipc, the args array identifies the endpoint or endpoints that the server should connect to. The server should validate the request, connect to the supplied endpoint promptly, and return a result with success: true when it accepts the request. If the server cannot open the channel, it should return success: false and include a short message when useful for logs.

An ipc endpoint is expected to provide a full-duplex JSON-RPC stream when the platform IPC mechanism supports it. In that case, args contains one endpoint string:

{ "type": "open", "kind": "ipc", "args": ["<full-duplex-ipc-endpoint>"] }

If the platform IPC mechanism exposes only one-way endpoints, args contains two endpoint strings. The endpoint names are from the type server's perspective: the first endpoint is the server input stream, and the second endpoint is the server output stream.

{ "type": "open", "kind": "ipc", "args": ["<input-ipc-endpoint>", "<output-ipc-endpoint>"] }

Closing An Extra Connection

The client closes an extra channel by sending typeServer/connection on the main connection with the same transport kind and endpoint identity:

{ "type": "close", "kind": "ipc", "args": ["<ipc-endpoint>"] }

The server should stop serving the matching extra channel and close the transport promptly. A client may also tear down its local transport if the server does not complete the close within the client's timeout budget.

The close request should use the same args shape that opened the channel: one endpoint for a full-duplex IPC stream, or the same input/output endpoint pair for a split IPC stream.

The main connection owns all state-changing traffic. The following must remain main-connection-only:

Extra connections are TSP-only and read-only. They may be used for requests that do not mutate server state and whose results are valid for the snapshot supplied by the client.

The allowed TSP messages on an extra connection are bound to the negotiated TSP version. If a server reports support for a TSP version and advertises multi-connection support for that session, it must support every extra-connection TSP message defined for that version.

The table below lists the TSP version that first allows each message on an extra connection:

Servers should reject LSP traffic, state-changing notifications, typeServer/connection, and any TSP message not allowed for the negotiated TSP version when received on an extra connection.

A snapshot is a non-negative integer that identifies a point-in-time view of the type server's analysis state. Type handles, declarations, symbols, and other returned objects are valid only for the snapshot in which they were returned unless a request explicitly says otherwise.

The type server must advance the snapshot whenever a previously returned type-analysis result may be invalid. Typical invalidating events include opened-file changes, closed files, configuration changes, watched-file changes, dependency changes, or any cache reset that changes analysis results.

If a type server stores source locations in another encoding, it must convert locations at the protocol boundary. Incorrect conversion can cause the client to request information for the wrong syntax node.

The type-query requests (typeServer/getComputedType, typeServer/getDeclaredType, typeServer/getExpectedType) identify a source construct with an arg that is either a node or a declaration. A node is a URI plus a source range. A declaration describes where and how a symbol is defined and is either a regular declaration, which is backed by a source AST node, or a synthesized declaration, which is created by the type checker and has no source node.

InvalidHandle is -1 and represents an invalid or unavailable handle. Clients and servers should treat it as a sentinel value, not as a valid object identifier.

Type results are JSON-serializable tagged objects. Each type includes a discriminator that tells the client how to interpret the rest of the object. The protocol supports built-in types, declared types, functions, classes, unions, modules, type variables, overload sets, synthesized types, and type references.

Every type object carries a numeric kind discriminator, a numeric id, and a bitfield of flags:

Type objects are snapshot-bound, and type IDs are response-local:

The current protocol is intentionally small. The exact parameters and result shapes are defined in the protocol artifacts; the table below lists every TSP message with its direction and payload shape.

A type server should implement the messages required by the client it integrates with and return undefined only where the protocol's result type allows it.

The three type-query requests differ by which type they report for the same node or declaration:

Errors should include enough message detail for a client log to identify the failed request, but they should not expose local secrets or implementation-only state.

A compatible type server should verify these behaviors:

Last content update aligned with Pylance 2026.4.1.