Type Server Protocol: what it adds over LSP, and which slot it takes in a Python type checking stack
The Type Server Protocol (TSP) is Microsoft's JSON-RPC protocol that lets an editor layer ask a separate Python type checker for types as structured data, not as hover text. In VS Code, it lets Pylance swap the checker underneath it. Microsoft announced it on 21 October 2026 together with Meta, whose Pyrefly is the first checker besides Pyright to plug in. The spec is at version 0.4.1. Posted to Hacker News on 26 October, it had about 240 points and over 150 comments a day later.
What is the Type Server Protocol?
The Type Server Protocol is a short list of JSON-RPC messages, all prefixed typeServer/, between a client and a type checker running in its own process. The spec defines it in one line: "The Type Server Protocol (TSP) is a JSON-RPC protocol for asking a type server for Python analysis data." The type server keeps the analysis state for a workspace and answers questions about it.
The spec calls the surface "intentionally small": nine messages. Three ask for types: the computed type after code flow narrowing, the declared type written in the source, and the type the surrounding code expects. Two resolve imports and search paths. The other four check the protocol version, track snapshots, so a stale answer can be refused and retried, and open or close extra read-only connections. It reuses the Language Server Protocol's positions and ranges, including its UTF-16 character offsets, which one Hacker News commenter asked to see changed.
A type server returns types as data, a language server returns them as text
The difference between a type server and a language server is who reads the answer. An LSP language server answers an editor, and its hover result is Markdown for a person. A TSP type server answers another program: each result is a typed object (class, function, union, type variable and so on, ten kinds in the spec's table) that the client can inspect. Micha Reiser of Astral summed it up on 26 March: "It is an API for computers, not humans."
In practice, TSP rides on an LSP connection. The client starts the checker, runs the normal LSP initialize handshake, then sends typeServer/* requests on the same stdio or IPC connection. The devblog calls TSP "an open standard that extends LSP". Today it is a 0.x document in the pylance-release repository, licensed CC BY 4.0, with one client. Rich Chiodo of Microsoft, who started it, wrote in March that he hoped for "a formal site" like LSP's. None exists yet.
One hover in Pylance becomes 265 type server requests
The spec folder includes captured traffic. In one capture, the user hovers over Parameter in from torch.nn import Parameter inside the PyTorch source. VS Code sends Pylance one LSP request:
{"method": "textDocument/hover",
"params": {"position": {"line": 9, "character": 21},
"textDocument": {"uri": "<workspaceRoot>/torch/distributed/pipelining/_backward.py"}}}Pylance then sends the Pyright type server 265 TSP requests for that hover by my count of the capture file: 240 typeServer/resolveImport calls and 25 typeServer/getComputedType calls. Chiodo explained in March that Pylance uses TSP to find the declaration of the type, not to build the hover string. On the TSP side the capture records requests only, sorted rather than in the order sent, with no responses or timings, so it shows how chatty the hop is but not how long it took.
At that volume the checker's speed matters. In a captured Pylance session with 43,811 getComputedType requests, Pyrefly 1.2.1 cut total TSP request time from about 671 seconds to about 6.4 seconds by no longer re-solving unopened modules for each request. Both figures are the Pyrefly team's.
TSP sits between Pylance and the checker, not in CI
TSP changes one hop in the editor: VS Code talks LSP to Pylance, and Pylance talks LSP plus TSP to a checker in a separate process. The devblog spells out the split: Pylance "becomes the VS Code IDE intelligence layer for Python, and the type checker becomes an interchangeable static analysis component underneath it." Completions, Quick Info, environment handling and the Copilot integration stay in Pylance whichever checker you pick.
Nothing in the spec covers the command line, so CI keeps whatever checker it runs: pyright, mypy, pyrefly check or ty. Astral's uv check belongs to that CI slot and has nothing to do with TSP. Announced on 13 October, it sets up the project environment and runs ty at the version pinned in the lockfile. It needs uv 0.12.3 and ty 0.0.76 or later, and it prints a warning that it "is experimental and may change without warning". The useful rule is version parity: run the same checker version in the editor and in CI. Unless python.analysis.pyreflyVersion names a version, Pylance looks for Pyrefly in the project's virtual environment first, which helps.
The Diagnostics Source setting that picks the checker behind Pylance. Image: Pyrefly + Pylance Integration in VS Code by the Pyrefly team (Meta), CC BY 4.0.
Pylance, Pyright and Pyrefly ship TSP; ty has a prototype
Three projects ship TSP today, and they are the ones Microsoft and Meta build. Pylance is the client, with Pyrefly as a backend from Pylance 2026.4.1, released 23 September. Pyright has shipped a standalone type server since 1.1.412 in August, published on npm as pyright-typeserver in September. Pyrefly has a pyrefly tsp command.
| Checker | TSP status, 27 Oct 2026 | Licence |
|---|---|---|
| Pyright | Ships a type server since 1.1.412 | MIT |
| Pyrefly | Ships pyrefly tsp; Pylance backend |
MIT |
| ty | Prototype by Microsoft; Phase 1 PR open, not usable end to end | MIT |
| basedpyright | Refuses to support it | MIT |
| mypy | No statement found | MIT |
| Pylance (client) | Ships; licensed only for Microsoft's editors | Proprietary |
The ty work comes from Microsoft, not Astral. Rich Chiodo's full implementation PR was closed unmerged in April, and his "Phase 1" PR "does not yet make TSP usable end-to-end". Reiser agreed to TSP in principle but called the benefits for Astral "limited" and said future TSP extension requests will be "evaluated case by case". Chiodo's benchmark on a private fork had ty faster in 21 of 28 comparisons. In one of those tests, by his own measurement, about 86% of the end-to-end time was spent in Pylance's code, not in the checker.
basedpyright's docs take the opposite side: "This protocol benefits nobody except microsoft. It adds needless complexity to any language server that chooses to support it." Its maintainer's argument is that Pylance stays closed source and tied to VS Code while the checkers underneath it become interchangeable.
TSP 0.4.1 is specified, the rest is intent
The 0.4.1 spec defines nine messages, snapshot rules, ten type kinds in its table (the TypeScript definitions next to it already add an eleventh), error codes and optional extra IPC connections. It carries no "draft" label, but warns: "While the protocol is in the 0.x line, minor version changes may be breaking." It has no open questions section. The TypeScript definition says the protocol is "Python specific at the moment, but may be made generic in the future."
Everything else is intent or extension. Intersection types and a plain string form of a type are not in the spec; Chiodo has called both easy to add. Pyrefly 1.4.0 already ships a pyrefly/typeFacts request that is not in the spec. Chiodo has guessed that future work would mostly help GitHub Copilot, with the type server feeding context and MCP tools. That is a plan, not a shipped feature. The sources also disagree on the minimum Pyrefly version: 0.60.0 in both blog posts, 1.1.1 in the Pylance README.
Who needs TSP and who can skip it
TSP matters to developers who use VS Code with Pylance and want a different checker's diagnostics without losing Pylance's completions or its Copilot integration. It also matters to tool authors who want structured types from a checker. Pyrefly's own team still recommends its standalone extension "for most users", and calls the Pylance route better for teams standardised on Pylance or relying on its Copilot integration.
Everyone else can skip it. Pylance is licensed only for Microsoft's editors and services, so Cursor, VSCodium, Neovim, Zed and PyCharm users cannot use it, and TSP does nothing for them today. Anyone already running one checker's own language server (ty, Pyrefly, basedpyright) gets nothing from it, and mypy has no type server at all. In CI, nothing changes.
On Stackness, as of 27 October 2026, VS Code is on 5 public stacks and uv on 1, which is mine; none lists mypy yet (how I count). The numbers are small. The editors and IDEs developers list show where Pylance users sit.
Where to start with the Type Server Protocol
Update Pylance to 2026.4.1 or later, install Pyrefly into the project's environment, and set the documented option in settings.json:
{
"python.analysis.diagnosticsSource": "Pylance + Pyrefly"
}To pin a version, set python.analysis.pyreflyVersion to a version string or a path to a local pyrefly binary. If Pylance cannot find or download Pyrefly, it switches back to Pylance. Then make CI run the same checker at the same version, pyrefly check here, so the editor and the pipeline agree. If you only want to read the protocol, start with the nine messages in the spec and the PyTorch captures next to it.
Type Server Protocol in brief
- Licence: spec CC BY 4.0, TypeScript definitions MIT; Pylance itself is proprietary.
- Version: 0.4.1; minor versions may break until 1.0.
- Transport: JSON-RPC over stdio or Node IPC, on the same connection as LSP.
- Editors: VS Code with Pylance only, as of 27 October 2026.
New posts by email
About one email a week with what we published. No account needed.
One email to confirm first. Every email has a one-click unsubscribe.
Which of these do you use?
Nobody on Stackness runs Type Server Protocol yet. Tick what you use and be the first.
