github-actions[bot]
1543 lines
81 KiB
HTML
1543 lines
81 KiB
HTML
<!DOCTYPE html><html lang="en" class="no-js"><head>
|
|
|
|
<meta charset="utf-8">
|
|
<meta name="viewport" content="width=device-width,initial-scale=1">
|
|
|
|
<meta name="description" content="MCP Server">
|
|
|
|
|
|
|
|
<link rel="canonical" href="https://modelcontextprotocol.github.io/python-sdk/low-level-server/">
|
|
|
|
|
|
<link rel="prev" href="../protocol/">
|
|
|
|
|
|
<link rel="next" href="../authorization/">
|
|
|
|
|
|
<link rel="icon" href="../assets/images/favicon.png">
|
|
<meta name="generator" content="mkdocs-1.6.1, mkdocs-material-9.6.19">
|
|
|
|
|
|
|
|
<title>Low-Level Server - MCP Server</title>
|
|
|
|
|
|
|
|
<link rel="stylesheet" href="../assets/stylesheets/main.7e37652d.min.css">
|
|
|
|
|
|
<link rel="stylesheet" href="../assets/stylesheets/palette.06af60db.min.css">
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
|
|
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto:300,300i,400,400i,700,700i%7CRoboto+Mono:400,400i,700,700i&display=fallback">
|
|
<style>:root{--md-text-font:"Roboto";--md-code-font:"Roboto Mono"}</style>
|
|
|
|
|
|
|
|
<link rel="stylesheet" href="../assets/_mkdocstrings.css">
|
|
|
|
<script>__md_scope=new URL("..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<meta property="og:type" content="website">
|
|
|
|
<meta property="og:title" content="Low-Level Server - MCP Server">
|
|
|
|
<meta property="og:description" content="MCP Server">
|
|
|
|
<meta property="og:image" content="https://modelcontextprotocol.github.io/python-sdk/assets/images/social/low-level-server.png">
|
|
|
|
<meta property="og:image:type" content="image/png">
|
|
|
|
<meta property="og:image:width" content="1200">
|
|
|
|
<meta property="og:image:height" content="630">
|
|
|
|
<meta property="og:url" content="https://modelcontextprotocol.github.io/python-sdk/low-level-server/">
|
|
|
|
<meta name="twitter:card" content="summary_large_image">
|
|
|
|
<meta name="twitter:title" content="Low-Level Server - MCP Server">
|
|
|
|
<meta name="twitter:description" content="MCP Server">
|
|
|
|
<meta name="twitter:image" content="https://modelcontextprotocol.github.io/python-sdk/assets/images/social/low-level-server.png">
|
|
|
|
|
|
|
|
<link href="../assets/stylesheets/glightbox.min.css" rel="stylesheet"><script src="../assets/javascripts/glightbox.min.js"></script><style id="glightbox-style">
|
|
html.glightbox-open { overflow: initial; height: 100%; }
|
|
.gslide-title { margin-top: 0px; user-select: text; }
|
|
.gslide-desc { color: #666; user-select: text; }
|
|
.gslide-image img { background: white; }
|
|
.gscrollbar-fixer { padding-right: 15px; }
|
|
.gdesc-inner { font-size: 0.75rem; }
|
|
body[data-md-color-scheme="slate"] .gdesc-inner { background: var(--md-default-bg-color); }
|
|
body[data-md-color-scheme="slate"] .gslide-title { color: var(--md-default-fg-color); }
|
|
body[data-md-color-scheme="slate"] .gslide-desc { color: var(--md-default-fg-color); }
|
|
</style></head>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<body dir="ltr" data-md-color-scheme="default" data-md-color-primary="black" data-md-color-accent="black">
|
|
|
|
|
|
<input class="md-toggle" data-md-toggle="drawer" type="checkbox" id="__drawer" autocomplete="off">
|
|
<input class="md-toggle" data-md-toggle="search" type="checkbox" id="__search" autocomplete="off">
|
|
<label class="md-overlay" for="__drawer"></label>
|
|
<div data-md-component="skip">
|
|
|
|
|
|
<a href="#low-level-server" class="md-skip">
|
|
Skip to content
|
|
</a>
|
|
|
|
</div>
|
|
<div data-md-component="announce">
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<header class="md-header md-header--shadow" data-md-component="header">
|
|
<nav class="md-header__inner md-grid" aria-label="Header">
|
|
<a href=".." title="MCP Server" class="md-header__button md-logo" aria-label="MCP Server" data-md-component="logo">
|
|
|
|
|
|
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54"></path></svg>
|
|
|
|
</a>
|
|
<label class="md-header__button md-icon" for="__drawer">
|
|
|
|
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"></path></svg>
|
|
</label>
|
|
<div class="md-header__title" data-md-component="header-title">
|
|
<div class="md-header__ellipsis">
|
|
<div class="md-header__topic">
|
|
<span class="md-ellipsis">
|
|
MCP Server
|
|
</span>
|
|
</div>
|
|
<div class="md-header__topic" data-md-component="header-topic">
|
|
<span class="md-ellipsis">
|
|
|
|
Low-Level Server
|
|
|
|
</span>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
|
|
<form class="md-header__option" data-md-component="palette">
|
|
|
|
|
|
|
|
|
|
<input class="md-option" data-md-color-media="(prefers-color-scheme)" data-md-color-scheme="default" data-md-color-primary="black" data-md-color-accent="black" aria-label="Switch to light mode" type="radio" name="__palette" id="__palette_0">
|
|
|
|
<label class="md-header__button md-icon" title="Switch to light mode" for="__palette_1" hidden>
|
|
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 2a7 7 0 0 0-7 7c0 2.38 1.19 4.47 3 5.74V17a1 1 0 0 0 1 1h6a1 1 0 0 0 1-1v-2.26c1.81-1.27 3-3.36 3-5.74a7 7 0 0 0-7-7M9 21a1 1 0 0 0 1 1h4a1 1 0 0 0 1-1v-1H9z"></path></svg>
|
|
</label>
|
|
|
|
|
|
|
|
|
|
|
|
<input class="md-option" data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme="default" data-md-color-primary="black" data-md-color-accent="black" aria-label="Switch to dark mode" type="radio" name="__palette" id="__palette_1">
|
|
|
|
<label class="md-header__button md-icon" title="Switch to dark mode" for="__palette_2" hidden>
|
|
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 2a7 7 0 0 1 7 7c0 2.38-1.19 4.47-3 5.74V17a1 1 0 0 1-1 1H9a1 1 0 0 1-1-1v-2.26C6.19 13.47 5 11.38 5 9a7 7 0 0 1 7-7M9 21v-1h6v1a1 1 0 0 1-1 1h-4a1 1 0 0 1-1-1m3-17a5 5 0 0 0-5 5c0 2.05 1.23 3.81 3 4.58V16h4v-2.42c1.77-.77 3-2.53 3-4.58a5 5 0 0 0-5-5"></path></svg>
|
|
</label>
|
|
|
|
|
|
|
|
|
|
|
|
<input class="md-option" data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme="slate" data-md-color-primary="white" data-md-color-accent="white" aria-label="Switch to system preference" type="radio" name="__palette" id="__palette_2">
|
|
|
|
<label class="md-header__button md-icon" title="Switch to system preference" for="__palette_0" hidden>
|
|
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9 2c3.87 0 7 3.13 7 7 0 2.38-1.19 4.47-3 5.74V17c0 .55-.45 1-1 1H6c-.55 0-1-.45-1-1v-2.26C3.19 13.47 2 11.38 2 9c0-3.87 3.13-7 7-7M6 21v-1h6v1c0 .55-.45 1-1 1H7c-.55 0-1-.45-1-1M9 4C6.24 4 4 6.24 4 9c0 2.05 1.23 3.81 3 4.58V16h4v-2.42c1.77-.77 3-2.53 3-4.58 0-2.76-2.24-5-5-5m10 9h-2l-3.2 9h1.9l.7-2h3.2l.7 2h1.9zm-2.15 5.65L18 15l1.15 3.65z"></path></svg>
|
|
</label>
|
|
|
|
|
|
</form>
|
|
|
|
|
|
|
|
<script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script>
|
|
|
|
|
|
|
|
|
|
|
|
<label class="md-header__button md-icon" for="__search">
|
|
|
|
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"></path></svg>
|
|
</label>
|
|
<div class="md-search" data-md-component="search" role="dialog">
|
|
<label class="md-search__overlay" for="__search"></label>
|
|
<div class="md-search__inner" role="search">
|
|
<form class="md-search__form" name="search">
|
|
<input type="text" class="md-search__input" name="query" aria-label="Search" placeholder="Search" autocapitalize="off" autocorrect="off" autocomplete="off" spellcheck="false" data-md-component="search-query" required>
|
|
<label class="md-search__icon md-icon" for="__search">
|
|
|
|
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"></path></svg>
|
|
|
|
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"></path></svg>
|
|
</label>
|
|
<nav class="md-search__options" aria-label="Search">
|
|
|
|
<button type="reset" class="md-search__icon md-icon" title="Clear" aria-label="Clear" tabindex="-1">
|
|
|
|
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M19 6.41 17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12z"></path></svg>
|
|
</button>
|
|
</nav>
|
|
|
|
<div class="md-search__suggest" data-md-component="search-suggest"></div>
|
|
|
|
</form>
|
|
<div class="md-search__output">
|
|
<div class="md-search__scrollwrap" tabindex="0" data-md-scrollfix>
|
|
<div class="md-search-result" data-md-component="search-result">
|
|
<div class="md-search-result__meta">
|
|
Initializing search
|
|
</div>
|
|
<ol class="md-search-result__list" role="presentation"></ol>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
|
|
|
|
<div class="md-header__source">
|
|
<a href="https://github.com/modelcontextprotocol/python-sdk" title="Go to repository" class="md-source" data-md-component="source">
|
|
<div class="md-source__icon md-icon">
|
|
|
|
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512"><!--! Font Awesome Free 7.0.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path fill="currentColor" d="M439.6 236.1 244 40.5c-5.4-5.5-12.8-8.5-20.4-8.5s-15 3-20.4 8.4L162.5 81l51.5 51.5c27.1-9.1 52.7 16.8 43.4 43.7l49.7 49.7c34.2-11.8 61.2 31 35.5 56.7-26.5 26.5-70.2-2.9-56-37.3L240.3 199v121.9c25.3 12.5 22.3 41.8 9.1 55-6.4 6.4-15.2 10.1-24.3 10.1s-17.8-3.6-24.3-10.1c-17.6-17.6-11.1-46.9 11.2-56v-123c-20.8-8.5-24.6-30.7-18.6-45L142.6 101 8.5 235.1C3 240.6 0 247.9 0 255.5s3 15 8.5 20.4l195.6 195.7c5.4 5.4 12.7 8.4 20.4 8.4s15-3 20.4-8.4l194.7-194.7c5.4-5.4 8.4-12.8 8.4-20.4s-3-15-8.4-20.4"></path></svg>
|
|
</div>
|
|
<div class="md-source__repository">
|
|
modelcontextprotocol/python-sdk
|
|
</div>
|
|
</a>
|
|
</div>
|
|
|
|
</nav>
|
|
|
|
</header>
|
|
|
|
<div class="md-container" data-md-component="container">
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<main class="md-main" data-md-component="main">
|
|
<div class="md-main__inner md-grid">
|
|
|
|
|
|
|
|
<div class="md-sidebar md-sidebar--primary" data-md-component="sidebar" data-md-type="navigation">
|
|
<div class="md-sidebar__scrollwrap">
|
|
<div class="md-sidebar__inner">
|
|
|
|
|
|
|
|
|
|
<nav class="md-nav md-nav--primary" aria-label="Navigation" data-md-level="0">
|
|
<label class="md-nav__title" for="__drawer">
|
|
<a href=".." title="MCP Server" class="md-nav__button md-logo" aria-label="MCP Server" data-md-component="logo">
|
|
|
|
|
|
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54"></path></svg>
|
|
|
|
</a>
|
|
MCP Server
|
|
</label>
|
|
|
|
<div class="md-nav__source">
|
|
<a href="https://github.com/modelcontextprotocol/python-sdk" title="Go to repository" class="md-source" data-md-component="source">
|
|
<div class="md-source__icon md-icon">
|
|
|
|
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512"><!--! Font Awesome Free 7.0.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path fill="currentColor" d="M439.6 236.1 244 40.5c-5.4-5.5-12.8-8.5-20.4-8.5s-15 3-20.4 8.4L162.5 81l51.5 51.5c27.1-9.1 52.7 16.8 43.4 43.7l49.7 49.7c34.2-11.8 61.2 31 35.5 56.7-26.5 26.5-70.2-2.9-56-37.3L240.3 199v121.9c25.3 12.5 22.3 41.8 9.1 55-6.4 6.4-15.2 10.1-24.3 10.1s-17.8-3.6-24.3-10.1c-17.6-17.6-11.1-46.9 11.2-56v-123c-20.8-8.5-24.6-30.7-18.6-45L142.6 101 8.5 235.1C3 240.6 0 247.9 0 255.5s3 15 8.5 20.4l195.6 195.7c5.4 5.4 12.7 8.4 20.4 8.4s15-3 20.4-8.4l194.7-194.7c5.4-5.4 8.4-12.8 8.4-20.4s-3-15-8.4-20.4"></path></svg>
|
|
</div>
|
|
<div class="md-source__repository">
|
|
modelcontextprotocol/python-sdk
|
|
</div>
|
|
</a>
|
|
</div>
|
|
|
|
<ul class="md-nav__list" data-md-scrollfix>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item">
|
|
<a href=".." class="md-nav__link">
|
|
|
|
|
|
|
|
<span class="md-ellipsis">
|
|
Introduction
|
|
|
|
</span>
|
|
|
|
|
|
</a>
|
|
</li>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item">
|
|
<a href="../installation/" class="md-nav__link">
|
|
|
|
|
|
|
|
<span class="md-ellipsis">
|
|
Installation
|
|
|
|
</span>
|
|
|
|
|
|
</a>
|
|
</li>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item md-nav__item--active md-nav__item--section md-nav__item--nested">
|
|
|
|
|
|
|
|
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_3" checked>
|
|
|
|
|
|
<label class="md-nav__link" for="__nav_3" id="__nav_3_label" tabindex="">
|
|
|
|
|
|
|
|
<span class="md-ellipsis">
|
|
Documentation
|
|
|
|
</span>
|
|
|
|
|
|
<span class="md-nav__icon md-icon"></span>
|
|
</label>
|
|
|
|
<nav class="md-nav" data-md-level="1" aria-labelledby="__nav_3_label" aria-expanded="true">
|
|
<label class="md-nav__title" for="__nav_3">
|
|
<span class="md-nav__icon md-icon"></span>
|
|
Documentation
|
|
</label>
|
|
<ul class="md-nav__list" data-md-scrollfix>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item">
|
|
<a href="../server/" class="md-nav__link">
|
|
|
|
|
|
|
|
<span class="md-ellipsis">
|
|
Building Servers
|
|
|
|
</span>
|
|
|
|
|
|
</a>
|
|
</li>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item">
|
|
<a href="../client/" class="md-nav__link">
|
|
|
|
|
|
|
|
<span class="md-ellipsis">
|
|
Writing Clients
|
|
|
|
</span>
|
|
|
|
|
|
</a>
|
|
</li>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item">
|
|
<a href="../protocol/" class="md-nav__link">
|
|
|
|
|
|
|
|
<span class="md-ellipsis">
|
|
Protocol Features
|
|
|
|
</span>
|
|
|
|
|
|
</a>
|
|
</li>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item md-nav__item--active">
|
|
|
|
<input class="md-nav__toggle md-toggle" type="checkbox" id="__toc">
|
|
|
|
|
|
|
|
|
|
|
|
<label class="md-nav__link md-nav__link--active" for="__toc">
|
|
|
|
|
|
|
|
<span class="md-ellipsis">
|
|
Low-Level Server
|
|
|
|
</span>
|
|
|
|
|
|
<span class="md-nav__icon md-icon"></span>
|
|
</label>
|
|
|
|
<a href="./" class="md-nav__link md-nav__link--active">
|
|
|
|
|
|
|
|
<span class="md-ellipsis">
|
|
Low-Level Server
|
|
|
|
</span>
|
|
|
|
|
|
</a>
|
|
|
|
|
|
|
|
<nav class="md-nav md-nav--secondary" aria-label="Table of contents">
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<label class="md-nav__title" for="__toc">
|
|
<span class="md-nav__icon md-icon"></span>
|
|
Table of contents
|
|
</label>
|
|
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#lifespan" class="md-nav__link">
|
|
<span class="md-ellipsis">
|
|
Lifespan
|
|
</span>
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#basic-example" class="md-nav__link">
|
|
<span class="md-ellipsis">
|
|
Basic Example
|
|
</span>
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#structured-output-support" class="md-nav__link">
|
|
<span class="md-ellipsis">
|
|
Structured Output Support
|
|
</span>
|
|
</a>
|
|
|
|
<nav class="md-nav" aria-label="Structured Output Support">
|
|
<ul class="md-nav__list">
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#returning-calltoolresult-directly" class="md-nav__link">
|
|
<span class="md-ellipsis">
|
|
Returning CallToolResult Directly
|
|
</span>
|
|
</a>
|
|
|
|
</li>
|
|
|
|
</ul>
|
|
</nav>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#pagination-advanced" class="md-nav__link">
|
|
<span class="md-ellipsis">
|
|
Pagination (Advanced)
|
|
</span>
|
|
</a>
|
|
|
|
<nav class="md-nav" aria-label="Pagination (Advanced)">
|
|
<ul class="md-nav__list">
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#server-side-implementation" class="md-nav__link">
|
|
<span class="md-ellipsis">
|
|
Server-side Implementation
|
|
</span>
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#client-side-consumption" class="md-nav__link">
|
|
<span class="md-ellipsis">
|
|
Client-side Consumption
|
|
</span>
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#key-points" class="md-nav__link">
|
|
<span class="md-ellipsis">
|
|
Key Points
|
|
</span>
|
|
</a>
|
|
|
|
</li>
|
|
|
|
</ul>
|
|
</nav>
|
|
|
|
</li>
|
|
|
|
</ul>
|
|
|
|
</nav>
|
|
|
|
</li>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item">
|
|
<a href="../authorization/" class="md-nav__link">
|
|
|
|
|
|
|
|
<span class="md-ellipsis">
|
|
Authorization
|
|
|
|
</span>
|
|
|
|
|
|
</a>
|
|
</li>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item">
|
|
<a href="../testing/" class="md-nav__link">
|
|
|
|
|
|
|
|
<span class="md-ellipsis">
|
|
Testing
|
|
|
|
</span>
|
|
|
|
|
|
</a>
|
|
</li>
|
|
|
|
|
|
|
|
|
|
</ul>
|
|
</nav>
|
|
|
|
</li>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item md-nav__item--section md-nav__item--nested">
|
|
|
|
|
|
|
|
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_4">
|
|
|
|
|
|
<div class="md-nav__link md-nav__container">
|
|
<a href="../experimental/" class="md-nav__link ">
|
|
|
|
|
|
|
|
<span class="md-ellipsis">
|
|
Experimental
|
|
|
|
</span>
|
|
|
|
|
|
</a>
|
|
|
|
|
|
<label class="md-nav__link " for="__nav_4" id="__nav_4_label" tabindex="">
|
|
<span class="md-nav__icon md-icon"></span>
|
|
</label>
|
|
|
|
</div>
|
|
|
|
<nav class="md-nav" data-md-level="1" aria-labelledby="__nav_4_label" aria-expanded="false">
|
|
<label class="md-nav__title" for="__nav_4">
|
|
<span class="md-nav__icon md-icon"></span>
|
|
Experimental
|
|
</label>
|
|
<ul class="md-nav__list" data-md-scrollfix>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item md-nav__item--nested">
|
|
|
|
|
|
|
|
<input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_4_2">
|
|
|
|
|
|
<label class="md-nav__link" for="__nav_4_2" id="__nav_4_2_label" tabindex="0">
|
|
|
|
|
|
|
|
<span class="md-ellipsis">
|
|
Tasks
|
|
|
|
</span>
|
|
|
|
|
|
<span class="md-nav__icon md-icon"></span>
|
|
</label>
|
|
|
|
<nav class="md-nav" data-md-level="2" aria-labelledby="__nav_4_2_label" aria-expanded="false">
|
|
<label class="md-nav__title" for="__nav_4_2">
|
|
<span class="md-nav__icon md-icon"></span>
|
|
Tasks
|
|
</label>
|
|
<ul class="md-nav__list" data-md-scrollfix>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item">
|
|
<a href="../experimental/tasks/" class="md-nav__link">
|
|
|
|
|
|
|
|
<span class="md-ellipsis">
|
|
Introduction
|
|
|
|
</span>
|
|
|
|
|
|
</a>
|
|
</li>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item">
|
|
<a href="../experimental/tasks-server/" class="md-nav__link">
|
|
|
|
|
|
|
|
<span class="md-ellipsis">
|
|
Server Implementation
|
|
|
|
</span>
|
|
|
|
|
|
</a>
|
|
</li>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item">
|
|
<a href="../experimental/tasks-client/" class="md-nav__link">
|
|
|
|
|
|
|
|
<span class="md-ellipsis">
|
|
Client Usage
|
|
|
|
</span>
|
|
|
|
|
|
</a>
|
|
</li>
|
|
|
|
|
|
|
|
|
|
</ul>
|
|
</nav>
|
|
|
|
</li>
|
|
|
|
|
|
|
|
|
|
</ul>
|
|
</nav>
|
|
|
|
</li>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<li class="md-nav__item">
|
|
<a href="../api/" class="md-nav__link">
|
|
|
|
|
|
|
|
<span class="md-ellipsis">
|
|
API Reference
|
|
|
|
</span>
|
|
|
|
|
|
</a>
|
|
</li>
|
|
|
|
|
|
|
|
</ul>
|
|
</nav>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
|
|
|
|
<div class="md-sidebar md-sidebar--secondary" data-md-component="sidebar" data-md-type="toc">
|
|
<div class="md-sidebar__scrollwrap">
|
|
<div class="md-sidebar__inner">
|
|
|
|
|
|
<nav class="md-nav md-nav--secondary" aria-label="Table of contents">
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<label class="md-nav__title" for="__toc">
|
|
<span class="md-nav__icon md-icon"></span>
|
|
Table of contents
|
|
</label>
|
|
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#lifespan" class="md-nav__link">
|
|
<span class="md-ellipsis">
|
|
Lifespan
|
|
</span>
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#basic-example" class="md-nav__link">
|
|
<span class="md-ellipsis">
|
|
Basic Example
|
|
</span>
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#structured-output-support" class="md-nav__link">
|
|
<span class="md-ellipsis">
|
|
Structured Output Support
|
|
</span>
|
|
</a>
|
|
|
|
<nav class="md-nav" aria-label="Structured Output Support">
|
|
<ul class="md-nav__list">
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#returning-calltoolresult-directly" class="md-nav__link">
|
|
<span class="md-ellipsis">
|
|
Returning CallToolResult Directly
|
|
</span>
|
|
</a>
|
|
|
|
</li>
|
|
|
|
</ul>
|
|
</nav>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#pagination-advanced" class="md-nav__link">
|
|
<span class="md-ellipsis">
|
|
Pagination (Advanced)
|
|
</span>
|
|
</a>
|
|
|
|
<nav class="md-nav" aria-label="Pagination (Advanced)">
|
|
<ul class="md-nav__list">
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#server-side-implementation" class="md-nav__link">
|
|
<span class="md-ellipsis">
|
|
Server-side Implementation
|
|
</span>
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#client-side-consumption" class="md-nav__link">
|
|
<span class="md-ellipsis">
|
|
Client-side Consumption
|
|
</span>
|
|
</a>
|
|
|
|
</li>
|
|
|
|
<li class="md-nav__item">
|
|
<a href="#key-points" class="md-nav__link">
|
|
<span class="md-ellipsis">
|
|
Key Points
|
|
</span>
|
|
</a>
|
|
|
|
</li>
|
|
|
|
</ul>
|
|
</nav>
|
|
|
|
</li>
|
|
|
|
</ul>
|
|
|
|
</nav>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
|
|
|
|
<div class="md-content" data-md-component="content">
|
|
<article class="md-content__inner md-typeset">
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<h1 id="low-level-server">Low-Level Server</h1>
|
|
<p>For more control, you can use the low-level server implementation directly. This gives you full access to the protocol and allows you to customize every aspect of your server, including lifecycle management through the lifespan API.</p>
|
|
<h2 id="lifespan">Lifespan</h2>
|
|
<!-- snippet-source examples/snippets/servers/lowlevel/lifespan.py -->
|
|
<div class="language-python highlight"><pre><span></span><code><span class="sd">"""</span>
|
|
<span class="sd">Run from the repository root:</span>
|
|
<span class="sd"> uv run examples/snippets/servers/lowlevel/lifespan.py</span>
|
|
<span class="sd">"""</span>
|
|
|
|
<span class="kn">from</span><span class="w"> </span><span class="nn">collections.abc</span><span class="w"> </span><span class="kn">import</span> <span class="n">AsyncIterator</span>
|
|
<span class="kn">from</span><span class="w"> </span><span class="nn">contextlib</span><span class="w"> </span><span class="kn">import</span> <span class="n">asynccontextmanager</span>
|
|
<span class="kn">from</span><span class="w"> </span><span class="nn">typing</span><span class="w"> </span><span class="kn">import</span> <span class="n">Any</span>
|
|
|
|
<span class="kn">import</span><span class="w"> </span><span class="nn">mcp.server.stdio</span>
|
|
<span class="kn">import</span><span class="w"> </span><span class="nn">mcp.types</span><span class="w"> </span><span class="k">as</span><span class="w"> </span><span class="nn">types</span>
|
|
<span class="kn">from</span><span class="w"> </span><span class="nn">mcp.server.lowlevel</span><span class="w"> </span><span class="kn">import</span> <span class="n">NotificationOptions</span><span class="p">,</span> <span class="n">Server</span>
|
|
<span class="kn">from</span><span class="w"> </span><span class="nn">mcp.server.models</span><span class="w"> </span><span class="kn">import</span> <span class="n">InitializationOptions</span>
|
|
|
|
|
|
<span class="c1"># Mock database class for example</span>
|
|
<span class="k">class</span><span class="w"> </span><span class="nc">Database</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="sd">"""Mock database class for example."""</span>
|
|
|
|
<span class="nd">@classmethod</span>
|
|
<span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">connect</span><span class="p">(</span><span class="bp">cls</span><span class="p">)</span> <span class="o">-></span> <span class="s2">"Database"</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="sd">"""Connect to database."""</span>
|
|
<span class="nb">print</span><span class="p">(</span><span class="s2">"Database connected"</span><span class="p">)</span>
|
|
<span class="k">return</span> <span class="bp">cls</span><span class="p">()</span>
|
|
|
|
<span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">disconnect</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span> <span class="o">-></span> <span class="kc">None</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="sd">"""Disconnect from database."""</span>
|
|
<span class="nb">print</span><span class="p">(</span><span class="s2">"Database disconnected"</span><span class="p">)</span>
|
|
|
|
<span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">query</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">query_str</span><span class="p">:</span> <span class="nb">str</span><span class="p">)</span> <span class="o">-></span> <span class="nb">list</span><span class="p">[</span><span class="nb">dict</span><span class="p">[</span><span class="nb">str</span><span class="p">,</span> <span class="nb">str</span><span class="p">]]:</span>
|
|
<span class="w"> </span><span class="sd">"""Execute a query."""</span>
|
|
<span class="c1"># Simulate database query</span>
|
|
<span class="k">return</span> <span class="p">[{</span><span class="s2">"id"</span><span class="p">:</span> <span class="s2">"1"</span><span class="p">,</span> <span class="s2">"name"</span><span class="p">:</span> <span class="s2">"Example"</span><span class="p">,</span> <span class="s2">"query"</span><span class="p">:</span> <span class="n">query_str</span><span class="p">}]</span>
|
|
|
|
|
|
<span class="nd">@asynccontextmanager</span>
|
|
<span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">server_lifespan</span><span class="p">(</span><span class="n">_server</span><span class="p">:</span> <span class="n">Server</span><span class="p">)</span> <span class="o">-></span> <span class="n">AsyncIterator</span><span class="p">[</span><span class="nb">dict</span><span class="p">[</span><span class="nb">str</span><span class="p">,</span> <span class="n">Any</span><span class="p">]]:</span>
|
|
<span class="w"> </span><span class="sd">"""Manage server startup and shutdown lifecycle."""</span>
|
|
<span class="c1"># Initialize resources on startup</span>
|
|
<span class="n">db</span> <span class="o">=</span> <span class="k">await</span> <span class="n">Database</span><span class="o">.</span><span class="n">connect</span><span class="p">()</span>
|
|
<span class="k">try</span><span class="p">:</span>
|
|
<span class="k">yield</span> <span class="p">{</span><span class="s2">"db"</span><span class="p">:</span> <span class="n">db</span><span class="p">}</span>
|
|
<span class="k">finally</span><span class="p">:</span>
|
|
<span class="c1"># Clean up on shutdown</span>
|
|
<span class="k">await</span> <span class="n">db</span><span class="o">.</span><span class="n">disconnect</span><span class="p">()</span>
|
|
|
|
|
|
<span class="c1"># Pass lifespan to server</span>
|
|
<span class="n">server</span> <span class="o">=</span> <span class="n">Server</span><span class="p">(</span><span class="s2">"example-server"</span><span class="p">,</span> <span class="n">lifespan</span><span class="o">=</span><span class="n">server_lifespan</span><span class="p">)</span>
|
|
|
|
|
|
<span class="nd">@server</span><span class="o">.</span><span class="n">list_tools</span><span class="p">()</span>
|
|
<span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">handle_list_tools</span><span class="p">()</span> <span class="o">-></span> <span class="nb">list</span><span class="p">[</span><span class="n">types</span><span class="o">.</span><span class="n">Tool</span><span class="p">]:</span>
|
|
<span class="w"> </span><span class="sd">"""List available tools."""</span>
|
|
<span class="k">return</span> <span class="p">[</span>
|
|
<span class="n">types</span><span class="o">.</span><span class="n">Tool</span><span class="p">(</span>
|
|
<span class="n">name</span><span class="o">=</span><span class="s2">"query_db"</span><span class="p">,</span>
|
|
<span class="n">description</span><span class="o">=</span><span class="s2">"Query the database"</span><span class="p">,</span>
|
|
<span class="n">inputSchema</span><span class="o">=</span><span class="p">{</span>
|
|
<span class="s2">"type"</span><span class="p">:</span> <span class="s2">"object"</span><span class="p">,</span>
|
|
<span class="s2">"properties"</span><span class="p">:</span> <span class="p">{</span><span class="s2">"query"</span><span class="p">:</span> <span class="p">{</span><span class="s2">"type"</span><span class="p">:</span> <span class="s2">"string"</span><span class="p">,</span> <span class="s2">"description"</span><span class="p">:</span> <span class="s2">"SQL query to execute"</span><span class="p">}},</span>
|
|
<span class="s2">"required"</span><span class="p">:</span> <span class="p">[</span><span class="s2">"query"</span><span class="p">],</span>
|
|
<span class="p">},</span>
|
|
<span class="p">)</span>
|
|
<span class="p">]</span>
|
|
|
|
|
|
<span class="nd">@server</span><span class="o">.</span><span class="n">call_tool</span><span class="p">()</span>
|
|
<span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">query_db</span><span class="p">(</span><span class="n">name</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span> <span class="n">arguments</span><span class="p">:</span> <span class="nb">dict</span><span class="p">[</span><span class="nb">str</span><span class="p">,</span> <span class="n">Any</span><span class="p">])</span> <span class="o">-></span> <span class="nb">list</span><span class="p">[</span><span class="n">types</span><span class="o">.</span><span class="n">TextContent</span><span class="p">]:</span>
|
|
<span class="w"> </span><span class="sd">"""Handle database query tool call."""</span>
|
|
<span class="k">if</span> <span class="n">name</span> <span class="o">!=</span> <span class="s2">"query_db"</span><span class="p">:</span>
|
|
<span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="sa">f</span><span class="s2">"Unknown tool: </span><span class="si">{</span><span class="n">name</span><span class="si">}</span><span class="s2">"</span><span class="p">)</span>
|
|
|
|
<span class="c1"># Access lifespan context</span>
|
|
<span class="n">ctx</span> <span class="o">=</span> <span class="n">server</span><span class="o">.</span><span class="n">request_context</span>
|
|
<span class="n">db</span> <span class="o">=</span> <span class="n">ctx</span><span class="o">.</span><span class="n">lifespan_context</span><span class="p">[</span><span class="s2">"db"</span><span class="p">]</span>
|
|
|
|
<span class="c1"># Execute query</span>
|
|
<span class="n">results</span> <span class="o">=</span> <span class="k">await</span> <span class="n">db</span><span class="o">.</span><span class="n">query</span><span class="p">(</span><span class="n">arguments</span><span class="p">[</span><span class="s2">"query"</span><span class="p">])</span>
|
|
|
|
<span class="k">return</span> <span class="p">[</span><span class="n">types</span><span class="o">.</span><span class="n">TextContent</span><span class="p">(</span><span class="nb">type</span><span class="o">=</span><span class="s2">"text"</span><span class="p">,</span> <span class="n">text</span><span class="o">=</span><span class="sa">f</span><span class="s2">"Query results: </span><span class="si">{</span><span class="n">results</span><span class="si">}</span><span class="s2">"</span><span class="p">)]</span>
|
|
|
|
|
|
<span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">run</span><span class="p">():</span>
|
|
<span class="w"> </span><span class="sd">"""Run the server with lifespan management."""</span>
|
|
<span class="k">async</span> <span class="k">with</span> <span class="n">mcp</span><span class="o">.</span><span class="n">server</span><span class="o">.</span><span class="n">stdio</span><span class="o">.</span><span class="n">stdio_server</span><span class="p">()</span> <span class="k">as</span> <span class="p">(</span><span class="n">read_stream</span><span class="p">,</span> <span class="n">write_stream</span><span class="p">):</span>
|
|
<span class="k">await</span> <span class="n">server</span><span class="o">.</span><span class="n">run</span><span class="p">(</span>
|
|
<span class="n">read_stream</span><span class="p">,</span>
|
|
<span class="n">write_stream</span><span class="p">,</span>
|
|
<span class="n">InitializationOptions</span><span class="p">(</span>
|
|
<span class="n">server_name</span><span class="o">=</span><span class="s2">"example-server"</span><span class="p">,</span>
|
|
<span class="n">server_version</span><span class="o">=</span><span class="s2">"0.1.0"</span><span class="p">,</span>
|
|
<span class="n">capabilities</span><span class="o">=</span><span class="n">server</span><span class="o">.</span><span class="n">get_capabilities</span><span class="p">(</span>
|
|
<span class="n">notification_options</span><span class="o">=</span><span class="n">NotificationOptions</span><span class="p">(),</span>
|
|
<span class="n">experimental_capabilities</span><span class="o">=</span><span class="p">{},</span>
|
|
<span class="p">),</span>
|
|
<span class="p">),</span>
|
|
<span class="p">)</span>
|
|
|
|
|
|
<span class="k">if</span> <span class="vm">__name__</span> <span class="o">==</span> <span class="s2">"__main__"</span><span class="p">:</span>
|
|
<span class="kn">import</span><span class="w"> </span><span class="nn">asyncio</span>
|
|
|
|
<span class="n">asyncio</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="n">run</span><span class="p">())</span>
|
|
</code></pre></div>
|
|
<p><em>Full example: <a href="https://github.com/modelcontextprotocol/python-sdk/blob/v1.x/examples/snippets/servers/lowlevel/lifespan.py">examples/snippets/servers/lowlevel/lifespan.py</a></em></p>
|
|
<!-- /snippet-source -->
|
|
|
|
<p>The lifespan API provides:</p>
|
|
<ul>
|
|
<li>A way to initialize resources when the server starts and clean them up when it stops</li>
|
|
<li>Access to initialized resources through the request context in handlers</li>
|
|
<li>Type-safe context passing between lifespan and request handlers</li>
|
|
</ul>
|
|
<h2 id="basic-example">Basic Example</h2>
|
|
<!-- snippet-source examples/snippets/servers/lowlevel/basic.py -->
|
|
<div class="language-python highlight"><pre><span></span><code><span class="sd">"""</span>
|
|
<span class="sd">Run from the repository root:</span>
|
|
<span class="sd">uv run examples/snippets/servers/lowlevel/basic.py</span>
|
|
<span class="sd">"""</span>
|
|
|
|
<span class="kn">import</span><span class="w"> </span><span class="nn">asyncio</span>
|
|
|
|
<span class="kn">import</span><span class="w"> </span><span class="nn">mcp.server.stdio</span>
|
|
<span class="kn">import</span><span class="w"> </span><span class="nn">mcp.types</span><span class="w"> </span><span class="k">as</span><span class="w"> </span><span class="nn">types</span>
|
|
<span class="kn">from</span><span class="w"> </span><span class="nn">mcp.server.lowlevel</span><span class="w"> </span><span class="kn">import</span> <span class="n">NotificationOptions</span><span class="p">,</span> <span class="n">Server</span>
|
|
<span class="kn">from</span><span class="w"> </span><span class="nn">mcp.server.models</span><span class="w"> </span><span class="kn">import</span> <span class="n">InitializationOptions</span>
|
|
|
|
<span class="c1"># Create a server instance</span>
|
|
<span class="n">server</span> <span class="o">=</span> <span class="n">Server</span><span class="p">(</span><span class="s2">"example-server"</span><span class="p">)</span>
|
|
|
|
|
|
<span class="nd">@server</span><span class="o">.</span><span class="n">list_prompts</span><span class="p">()</span>
|
|
<span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">handle_list_prompts</span><span class="p">()</span> <span class="o">-></span> <span class="nb">list</span><span class="p">[</span><span class="n">types</span><span class="o">.</span><span class="n">Prompt</span><span class="p">]:</span>
|
|
<span class="w"> </span><span class="sd">"""List available prompts."""</span>
|
|
<span class="k">return</span> <span class="p">[</span>
|
|
<span class="n">types</span><span class="o">.</span><span class="n">Prompt</span><span class="p">(</span>
|
|
<span class="n">name</span><span class="o">=</span><span class="s2">"example-prompt"</span><span class="p">,</span>
|
|
<span class="n">description</span><span class="o">=</span><span class="s2">"An example prompt template"</span><span class="p">,</span>
|
|
<span class="n">arguments</span><span class="o">=</span><span class="p">[</span><span class="n">types</span><span class="o">.</span><span class="n">PromptArgument</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s2">"arg1"</span><span class="p">,</span> <span class="n">description</span><span class="o">=</span><span class="s2">"Example argument"</span><span class="p">,</span> <span class="n">required</span><span class="o">=</span><span class="kc">True</span><span class="p">)],</span>
|
|
<span class="p">)</span>
|
|
<span class="p">]</span>
|
|
|
|
|
|
<span class="nd">@server</span><span class="o">.</span><span class="n">get_prompt</span><span class="p">()</span>
|
|
<span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">handle_get_prompt</span><span class="p">(</span><span class="n">name</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span> <span class="n">arguments</span><span class="p">:</span> <span class="nb">dict</span><span class="p">[</span><span class="nb">str</span><span class="p">,</span> <span class="nb">str</span><span class="p">]</span> <span class="o">|</span> <span class="kc">None</span><span class="p">)</span> <span class="o">-></span> <span class="n">types</span><span class="o">.</span><span class="n">GetPromptResult</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="sd">"""Get a specific prompt by name."""</span>
|
|
<span class="k">if</span> <span class="n">name</span> <span class="o">!=</span> <span class="s2">"example-prompt"</span><span class="p">:</span>
|
|
<span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="sa">f</span><span class="s2">"Unknown prompt: </span><span class="si">{</span><span class="n">name</span><span class="si">}</span><span class="s2">"</span><span class="p">)</span>
|
|
|
|
<span class="n">arg1_value</span> <span class="o">=</span> <span class="p">(</span><span class="n">arguments</span> <span class="ow">or</span> <span class="p">{})</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">"arg1"</span><span class="p">,</span> <span class="s2">"default"</span><span class="p">)</span>
|
|
|
|
<span class="k">return</span> <span class="n">types</span><span class="o">.</span><span class="n">GetPromptResult</span><span class="p">(</span>
|
|
<span class="n">description</span><span class="o">=</span><span class="s2">"Example prompt"</span><span class="p">,</span>
|
|
<span class="n">messages</span><span class="o">=</span><span class="p">[</span>
|
|
<span class="n">types</span><span class="o">.</span><span class="n">PromptMessage</span><span class="p">(</span>
|
|
<span class="n">role</span><span class="o">=</span><span class="s2">"user"</span><span class="p">,</span>
|
|
<span class="n">content</span><span class="o">=</span><span class="n">types</span><span class="o">.</span><span class="n">TextContent</span><span class="p">(</span><span class="nb">type</span><span class="o">=</span><span class="s2">"text"</span><span class="p">,</span> <span class="n">text</span><span class="o">=</span><span class="sa">f</span><span class="s2">"Example prompt text with argument: </span><span class="si">{</span><span class="n">arg1_value</span><span class="si">}</span><span class="s2">"</span><span class="p">),</span>
|
|
<span class="p">)</span>
|
|
<span class="p">],</span>
|
|
<span class="p">)</span>
|
|
|
|
|
|
<span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">run</span><span class="p">():</span>
|
|
<span class="w"> </span><span class="sd">"""Run the basic low-level server."""</span>
|
|
<span class="k">async</span> <span class="k">with</span> <span class="n">mcp</span><span class="o">.</span><span class="n">server</span><span class="o">.</span><span class="n">stdio</span><span class="o">.</span><span class="n">stdio_server</span><span class="p">()</span> <span class="k">as</span> <span class="p">(</span><span class="n">read_stream</span><span class="p">,</span> <span class="n">write_stream</span><span class="p">):</span>
|
|
<span class="k">await</span> <span class="n">server</span><span class="o">.</span><span class="n">run</span><span class="p">(</span>
|
|
<span class="n">read_stream</span><span class="p">,</span>
|
|
<span class="n">write_stream</span><span class="p">,</span>
|
|
<span class="n">InitializationOptions</span><span class="p">(</span>
|
|
<span class="n">server_name</span><span class="o">=</span><span class="s2">"example"</span><span class="p">,</span>
|
|
<span class="n">server_version</span><span class="o">=</span><span class="s2">"0.1.0"</span><span class="p">,</span>
|
|
<span class="n">capabilities</span><span class="o">=</span><span class="n">server</span><span class="o">.</span><span class="n">get_capabilities</span><span class="p">(</span>
|
|
<span class="n">notification_options</span><span class="o">=</span><span class="n">NotificationOptions</span><span class="p">(),</span>
|
|
<span class="n">experimental_capabilities</span><span class="o">=</span><span class="p">{},</span>
|
|
<span class="p">),</span>
|
|
<span class="p">),</span>
|
|
<span class="p">)</span>
|
|
|
|
|
|
<span class="k">if</span> <span class="vm">__name__</span> <span class="o">==</span> <span class="s2">"__main__"</span><span class="p">:</span>
|
|
<span class="n">asyncio</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="n">run</span><span class="p">())</span>
|
|
</code></pre></div>
|
|
<p><em>Full example: <a href="https://github.com/modelcontextprotocol/python-sdk/blob/v1.x/examples/snippets/servers/lowlevel/basic.py">examples/snippets/servers/lowlevel/basic.py</a></em></p>
|
|
<!-- /snippet-source -->
|
|
|
|
<p>Caution: The <code>uv run mcp run</code> and <code>uv run mcp dev</code> tool doesn't support low-level server.</p>
|
|
<h2 id="structured-output-support">Structured Output Support</h2>
|
|
<p>The low-level server supports structured output for tools, allowing you to return both human-readable content and machine-readable structured data. Tools can define an <code>outputSchema</code> to validate their structured output:</p>
|
|
<!-- snippet-source examples/snippets/servers/lowlevel/structured_output.py -->
|
|
<div class="language-python highlight"><pre><span></span><code><span class="sd">"""</span>
|
|
<span class="sd">Run from the repository root:</span>
|
|
<span class="sd"> uv run examples/snippets/servers/lowlevel/structured_output.py</span>
|
|
<span class="sd">"""</span>
|
|
|
|
<span class="kn">import</span><span class="w"> </span><span class="nn">asyncio</span>
|
|
<span class="kn">from</span><span class="w"> </span><span class="nn">typing</span><span class="w"> </span><span class="kn">import</span> <span class="n">Any</span>
|
|
|
|
<span class="kn">import</span><span class="w"> </span><span class="nn">mcp.server.stdio</span>
|
|
<span class="kn">import</span><span class="w"> </span><span class="nn">mcp.types</span><span class="w"> </span><span class="k">as</span><span class="w"> </span><span class="nn">types</span>
|
|
<span class="kn">from</span><span class="w"> </span><span class="nn">mcp.server.lowlevel</span><span class="w"> </span><span class="kn">import</span> <span class="n">NotificationOptions</span><span class="p">,</span> <span class="n">Server</span>
|
|
<span class="kn">from</span><span class="w"> </span><span class="nn">mcp.server.models</span><span class="w"> </span><span class="kn">import</span> <span class="n">InitializationOptions</span>
|
|
|
|
<span class="n">server</span> <span class="o">=</span> <span class="n">Server</span><span class="p">(</span><span class="s2">"example-server"</span><span class="p">)</span>
|
|
|
|
|
|
<span class="nd">@server</span><span class="o">.</span><span class="n">list_tools</span><span class="p">()</span>
|
|
<span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">list_tools</span><span class="p">()</span> <span class="o">-></span> <span class="nb">list</span><span class="p">[</span><span class="n">types</span><span class="o">.</span><span class="n">Tool</span><span class="p">]:</span>
|
|
<span class="w"> </span><span class="sd">"""List available tools with structured output schemas."""</span>
|
|
<span class="k">return</span> <span class="p">[</span>
|
|
<span class="n">types</span><span class="o">.</span><span class="n">Tool</span><span class="p">(</span>
|
|
<span class="n">name</span><span class="o">=</span><span class="s2">"get_weather"</span><span class="p">,</span>
|
|
<span class="n">description</span><span class="o">=</span><span class="s2">"Get current weather for a city"</span><span class="p">,</span>
|
|
<span class="n">inputSchema</span><span class="o">=</span><span class="p">{</span>
|
|
<span class="s2">"type"</span><span class="p">:</span> <span class="s2">"object"</span><span class="p">,</span>
|
|
<span class="s2">"properties"</span><span class="p">:</span> <span class="p">{</span><span class="s2">"city"</span><span class="p">:</span> <span class="p">{</span><span class="s2">"type"</span><span class="p">:</span> <span class="s2">"string"</span><span class="p">,</span> <span class="s2">"description"</span><span class="p">:</span> <span class="s2">"City name"</span><span class="p">}},</span>
|
|
<span class="s2">"required"</span><span class="p">:</span> <span class="p">[</span><span class="s2">"city"</span><span class="p">],</span>
|
|
<span class="p">},</span>
|
|
<span class="n">outputSchema</span><span class="o">=</span><span class="p">{</span>
|
|
<span class="s2">"type"</span><span class="p">:</span> <span class="s2">"object"</span><span class="p">,</span>
|
|
<span class="s2">"properties"</span><span class="p">:</span> <span class="p">{</span>
|
|
<span class="s2">"temperature"</span><span class="p">:</span> <span class="p">{</span><span class="s2">"type"</span><span class="p">:</span> <span class="s2">"number"</span><span class="p">,</span> <span class="s2">"description"</span><span class="p">:</span> <span class="s2">"Temperature in Celsius"</span><span class="p">},</span>
|
|
<span class="s2">"condition"</span><span class="p">:</span> <span class="p">{</span><span class="s2">"type"</span><span class="p">:</span> <span class="s2">"string"</span><span class="p">,</span> <span class="s2">"description"</span><span class="p">:</span> <span class="s2">"Weather condition"</span><span class="p">},</span>
|
|
<span class="s2">"humidity"</span><span class="p">:</span> <span class="p">{</span><span class="s2">"type"</span><span class="p">:</span> <span class="s2">"number"</span><span class="p">,</span> <span class="s2">"description"</span><span class="p">:</span> <span class="s2">"Humidity percentage"</span><span class="p">},</span>
|
|
<span class="s2">"city"</span><span class="p">:</span> <span class="p">{</span><span class="s2">"type"</span><span class="p">:</span> <span class="s2">"string"</span><span class="p">,</span> <span class="s2">"description"</span><span class="p">:</span> <span class="s2">"City name"</span><span class="p">},</span>
|
|
<span class="p">},</span>
|
|
<span class="s2">"required"</span><span class="p">:</span> <span class="p">[</span><span class="s2">"temperature"</span><span class="p">,</span> <span class="s2">"condition"</span><span class="p">,</span> <span class="s2">"humidity"</span><span class="p">,</span> <span class="s2">"city"</span><span class="p">],</span>
|
|
<span class="p">},</span>
|
|
<span class="p">)</span>
|
|
<span class="p">]</span>
|
|
|
|
|
|
<span class="nd">@server</span><span class="o">.</span><span class="n">call_tool</span><span class="p">()</span>
|
|
<span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">call_tool</span><span class="p">(</span><span class="n">name</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span> <span class="n">arguments</span><span class="p">:</span> <span class="nb">dict</span><span class="p">[</span><span class="nb">str</span><span class="p">,</span> <span class="n">Any</span><span class="p">])</span> <span class="o">-></span> <span class="nb">dict</span><span class="p">[</span><span class="nb">str</span><span class="p">,</span> <span class="n">Any</span><span class="p">]:</span>
|
|
<span class="w"> </span><span class="sd">"""Handle tool calls with structured output."""</span>
|
|
<span class="k">if</span> <span class="n">name</span> <span class="o">==</span> <span class="s2">"get_weather"</span><span class="p">:</span>
|
|
<span class="n">city</span> <span class="o">=</span> <span class="n">arguments</span><span class="p">[</span><span class="s2">"city"</span><span class="p">]</span>
|
|
|
|
<span class="c1"># Simulated weather data - in production, call a weather API</span>
|
|
<span class="n">weather_data</span> <span class="o">=</span> <span class="p">{</span>
|
|
<span class="s2">"temperature"</span><span class="p">:</span> <span class="mf">22.5</span><span class="p">,</span>
|
|
<span class="s2">"condition"</span><span class="p">:</span> <span class="s2">"partly cloudy"</span><span class="p">,</span>
|
|
<span class="s2">"humidity"</span><span class="p">:</span> <span class="mi">65</span><span class="p">,</span>
|
|
<span class="s2">"city"</span><span class="p">:</span> <span class="n">city</span><span class="p">,</span> <span class="c1"># Include the requested city</span>
|
|
<span class="p">}</span>
|
|
|
|
<span class="c1"># low-level server will validate structured output against the tool's</span>
|
|
<span class="c1"># output schema, and additionally serialize it into a TextContent block</span>
|
|
<span class="c1"># for backwards compatibility with pre-2025-06-18 clients.</span>
|
|
<span class="k">return</span> <span class="n">weather_data</span>
|
|
<span class="k">else</span><span class="p">:</span>
|
|
<span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="sa">f</span><span class="s2">"Unknown tool: </span><span class="si">{</span><span class="n">name</span><span class="si">}</span><span class="s2">"</span><span class="p">)</span>
|
|
|
|
|
|
<span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">run</span><span class="p">():</span>
|
|
<span class="w"> </span><span class="sd">"""Run the structured output server."""</span>
|
|
<span class="k">async</span> <span class="k">with</span> <span class="n">mcp</span><span class="o">.</span><span class="n">server</span><span class="o">.</span><span class="n">stdio</span><span class="o">.</span><span class="n">stdio_server</span><span class="p">()</span> <span class="k">as</span> <span class="p">(</span><span class="n">read_stream</span><span class="p">,</span> <span class="n">write_stream</span><span class="p">):</span>
|
|
<span class="k">await</span> <span class="n">server</span><span class="o">.</span><span class="n">run</span><span class="p">(</span>
|
|
<span class="n">read_stream</span><span class="p">,</span>
|
|
<span class="n">write_stream</span><span class="p">,</span>
|
|
<span class="n">InitializationOptions</span><span class="p">(</span>
|
|
<span class="n">server_name</span><span class="o">=</span><span class="s2">"structured-output-example"</span><span class="p">,</span>
|
|
<span class="n">server_version</span><span class="o">=</span><span class="s2">"0.1.0"</span><span class="p">,</span>
|
|
<span class="n">capabilities</span><span class="o">=</span><span class="n">server</span><span class="o">.</span><span class="n">get_capabilities</span><span class="p">(</span>
|
|
<span class="n">notification_options</span><span class="o">=</span><span class="n">NotificationOptions</span><span class="p">(),</span>
|
|
<span class="n">experimental_capabilities</span><span class="o">=</span><span class="p">{},</span>
|
|
<span class="p">),</span>
|
|
<span class="p">),</span>
|
|
<span class="p">)</span>
|
|
|
|
|
|
<span class="k">if</span> <span class="vm">__name__</span> <span class="o">==</span> <span class="s2">"__main__"</span><span class="p">:</span>
|
|
<span class="n">asyncio</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="n">run</span><span class="p">())</span>
|
|
</code></pre></div>
|
|
<p><em>Full example: <a href="https://github.com/modelcontextprotocol/python-sdk/blob/v1.x/examples/snippets/servers/lowlevel/structured_output.py">examples/snippets/servers/lowlevel/structured_output.py</a></em></p>
|
|
<!-- /snippet-source -->
|
|
|
|
<p>Tools can return data in four ways:</p>
|
|
<ol>
|
|
<li><strong>Content only</strong>: Return a list of content blocks (default behavior before spec revision 2025-06-18)</li>
|
|
<li><strong>Structured data only</strong>: Return a dictionary that will be serialized to JSON (Introduced in spec revision 2025-06-18)</li>
|
|
<li><strong>Both</strong>: Return a tuple of (content, structured_data) preferred option to use for backwards compatibility</li>
|
|
<li><strong>Direct CallToolResult</strong>: Return <code>CallToolResult</code> directly for full control (including <code>_meta</code> field)</li>
|
|
</ol>
|
|
<p>When an <code>outputSchema</code> is defined, the server automatically validates the structured output against the schema. This ensures type safety and helps catch errors early.</p>
|
|
<h3 id="returning-calltoolresult-directly">Returning CallToolResult Directly</h3>
|
|
<p>For full control over the response including the <code>_meta</code> field (for passing data to client applications without exposing it to the model), return <code>CallToolResult</code> directly:</p>
|
|
<!-- snippet-source examples/snippets/servers/lowlevel/direct_call_tool_result.py -->
|
|
<div class="language-python highlight"><pre><span></span><code><span class="sd">"""</span>
|
|
<span class="sd">Run from the repository root:</span>
|
|
<span class="sd"> uv run examples/snippets/servers/lowlevel/direct_call_tool_result.py</span>
|
|
<span class="sd">"""</span>
|
|
|
|
<span class="kn">import</span><span class="w"> </span><span class="nn">asyncio</span>
|
|
<span class="kn">from</span><span class="w"> </span><span class="nn">typing</span><span class="w"> </span><span class="kn">import</span> <span class="n">Any</span>
|
|
|
|
<span class="kn">import</span><span class="w"> </span><span class="nn">mcp.server.stdio</span>
|
|
<span class="kn">import</span><span class="w"> </span><span class="nn">mcp.types</span><span class="w"> </span><span class="k">as</span><span class="w"> </span><span class="nn">types</span>
|
|
<span class="kn">from</span><span class="w"> </span><span class="nn">mcp.server.lowlevel</span><span class="w"> </span><span class="kn">import</span> <span class="n">NotificationOptions</span><span class="p">,</span> <span class="n">Server</span>
|
|
<span class="kn">from</span><span class="w"> </span><span class="nn">mcp.server.models</span><span class="w"> </span><span class="kn">import</span> <span class="n">InitializationOptions</span>
|
|
|
|
<span class="n">server</span> <span class="o">=</span> <span class="n">Server</span><span class="p">(</span><span class="s2">"example-server"</span><span class="p">)</span>
|
|
|
|
|
|
<span class="nd">@server</span><span class="o">.</span><span class="n">list_tools</span><span class="p">()</span>
|
|
<span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">list_tools</span><span class="p">()</span> <span class="o">-></span> <span class="nb">list</span><span class="p">[</span><span class="n">types</span><span class="o">.</span><span class="n">Tool</span><span class="p">]:</span>
|
|
<span class="w"> </span><span class="sd">"""List available tools."""</span>
|
|
<span class="k">return</span> <span class="p">[</span>
|
|
<span class="n">types</span><span class="o">.</span><span class="n">Tool</span><span class="p">(</span>
|
|
<span class="n">name</span><span class="o">=</span><span class="s2">"advanced_tool"</span><span class="p">,</span>
|
|
<span class="n">description</span><span class="o">=</span><span class="s2">"Tool with full control including _meta field"</span><span class="p">,</span>
|
|
<span class="n">inputSchema</span><span class="o">=</span><span class="p">{</span>
|
|
<span class="s2">"type"</span><span class="p">:</span> <span class="s2">"object"</span><span class="p">,</span>
|
|
<span class="s2">"properties"</span><span class="p">:</span> <span class="p">{</span><span class="s2">"message"</span><span class="p">:</span> <span class="p">{</span><span class="s2">"type"</span><span class="p">:</span> <span class="s2">"string"</span><span class="p">}},</span>
|
|
<span class="s2">"required"</span><span class="p">:</span> <span class="p">[</span><span class="s2">"message"</span><span class="p">],</span>
|
|
<span class="p">},</span>
|
|
<span class="p">)</span>
|
|
<span class="p">]</span>
|
|
|
|
|
|
<span class="nd">@server</span><span class="o">.</span><span class="n">call_tool</span><span class="p">()</span>
|
|
<span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">handle_call_tool</span><span class="p">(</span><span class="n">name</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span> <span class="n">arguments</span><span class="p">:</span> <span class="nb">dict</span><span class="p">[</span><span class="nb">str</span><span class="p">,</span> <span class="n">Any</span><span class="p">])</span> <span class="o">-></span> <span class="n">types</span><span class="o">.</span><span class="n">CallToolResult</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="sd">"""Handle tool calls by returning CallToolResult directly."""</span>
|
|
<span class="k">if</span> <span class="n">name</span> <span class="o">==</span> <span class="s2">"advanced_tool"</span><span class="p">:</span>
|
|
<span class="n">message</span> <span class="o">=</span> <span class="nb">str</span><span class="p">(</span><span class="n">arguments</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">"message"</span><span class="p">,</span> <span class="s2">""</span><span class="p">))</span>
|
|
<span class="k">return</span> <span class="n">types</span><span class="o">.</span><span class="n">CallToolResult</span><span class="p">(</span>
|
|
<span class="n">content</span><span class="o">=</span><span class="p">[</span><span class="n">types</span><span class="o">.</span><span class="n">TextContent</span><span class="p">(</span><span class="nb">type</span><span class="o">=</span><span class="s2">"text"</span><span class="p">,</span> <span class="n">text</span><span class="o">=</span><span class="sa">f</span><span class="s2">"Processed: </span><span class="si">{</span><span class="n">message</span><span class="si">}</span><span class="s2">"</span><span class="p">)],</span>
|
|
<span class="n">structuredContent</span><span class="o">=</span><span class="p">{</span><span class="s2">"result"</span><span class="p">:</span> <span class="s2">"success"</span><span class="p">,</span> <span class="s2">"message"</span><span class="p">:</span> <span class="n">message</span><span class="p">},</span>
|
|
<span class="n">_meta</span><span class="o">=</span><span class="p">{</span><span class="s2">"hidden"</span><span class="p">:</span> <span class="s2">"data for client applications only"</span><span class="p">},</span>
|
|
<span class="p">)</span>
|
|
|
|
<span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="sa">f</span><span class="s2">"Unknown tool: </span><span class="si">{</span><span class="n">name</span><span class="si">}</span><span class="s2">"</span><span class="p">)</span>
|
|
|
|
|
|
<span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">run</span><span class="p">():</span>
|
|
<span class="w"> </span><span class="sd">"""Run the server."""</span>
|
|
<span class="k">async</span> <span class="k">with</span> <span class="n">mcp</span><span class="o">.</span><span class="n">server</span><span class="o">.</span><span class="n">stdio</span><span class="o">.</span><span class="n">stdio_server</span><span class="p">()</span> <span class="k">as</span> <span class="p">(</span><span class="n">read_stream</span><span class="p">,</span> <span class="n">write_stream</span><span class="p">):</span>
|
|
<span class="k">await</span> <span class="n">server</span><span class="o">.</span><span class="n">run</span><span class="p">(</span>
|
|
<span class="n">read_stream</span><span class="p">,</span>
|
|
<span class="n">write_stream</span><span class="p">,</span>
|
|
<span class="n">InitializationOptions</span><span class="p">(</span>
|
|
<span class="n">server_name</span><span class="o">=</span><span class="s2">"example"</span><span class="p">,</span>
|
|
<span class="n">server_version</span><span class="o">=</span><span class="s2">"0.1.0"</span><span class="p">,</span>
|
|
<span class="n">capabilities</span><span class="o">=</span><span class="n">server</span><span class="o">.</span><span class="n">get_capabilities</span><span class="p">(</span>
|
|
<span class="n">notification_options</span><span class="o">=</span><span class="n">NotificationOptions</span><span class="p">(),</span>
|
|
<span class="n">experimental_capabilities</span><span class="o">=</span><span class="p">{},</span>
|
|
<span class="p">),</span>
|
|
<span class="p">),</span>
|
|
<span class="p">)</span>
|
|
|
|
|
|
<span class="k">if</span> <span class="vm">__name__</span> <span class="o">==</span> <span class="s2">"__main__"</span><span class="p">:</span>
|
|
<span class="n">asyncio</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="n">run</span><span class="p">())</span>
|
|
</code></pre></div>
|
|
<p><em>Full example: <a href="https://github.com/modelcontextprotocol/python-sdk/blob/v1.x/examples/snippets/servers/lowlevel/direct_call_tool_result.py">examples/snippets/servers/lowlevel/direct_call_tool_result.py</a></em></p>
|
|
<!-- /snippet-source -->
|
|
|
|
<p><strong>Note:</strong> When returning <code>CallToolResult</code>, you bypass the automatic content/structured conversion. You must construct the complete response yourself.</p>
|
|
<h2 id="pagination-advanced">Pagination (Advanced)</h2>
|
|
<p>For servers that need to handle large datasets, the low-level server provides paginated versions of list operations. This is an optional optimization - most servers won't need pagination unless they're dealing with hundreds or thousands of items.</p>
|
|
<h3 id="server-side-implementation">Server-side Implementation</h3>
|
|
<!-- snippet-source examples/snippets/servers/pagination_example.py -->
|
|
<div class="language-python highlight"><pre><span></span><code><span class="sd">"""</span>
|
|
<span class="sd">Example of implementing pagination with MCP server decorators.</span>
|
|
<span class="sd">"""</span>
|
|
|
|
<span class="kn">from</span><span class="w"> </span><span class="nn">pydantic</span><span class="w"> </span><span class="kn">import</span> <span class="n">AnyUrl</span>
|
|
|
|
<span class="kn">import</span><span class="w"> </span><span class="nn">mcp.types</span><span class="w"> </span><span class="k">as</span><span class="w"> </span><span class="nn">types</span>
|
|
<span class="kn">from</span><span class="w"> </span><span class="nn">mcp.server.lowlevel</span><span class="w"> </span><span class="kn">import</span> <span class="n">Server</span>
|
|
|
|
<span class="c1"># Initialize the server</span>
|
|
<span class="n">server</span> <span class="o">=</span> <span class="n">Server</span><span class="p">(</span><span class="s2">"paginated-server"</span><span class="p">)</span>
|
|
|
|
<span class="c1"># Sample data to paginate</span>
|
|
<span class="n">ITEMS</span> <span class="o">=</span> <span class="p">[</span><span class="sa">f</span><span class="s2">"Item </span><span class="si">{</span><span class="n">i</span><span class="si">}</span><span class="s2">"</span> <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">101</span><span class="p">)]</span> <span class="c1"># 100 items</span>
|
|
|
|
|
|
<span class="nd">@server</span><span class="o">.</span><span class="n">list_resources</span><span class="p">()</span>
|
|
<span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">list_resources_paginated</span><span class="p">(</span><span class="n">request</span><span class="p">:</span> <span class="n">types</span><span class="o">.</span><span class="n">ListResourcesRequest</span><span class="p">)</span> <span class="o">-></span> <span class="n">types</span><span class="o">.</span><span class="n">ListResourcesResult</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="sd">"""List resources with pagination support."""</span>
|
|
<span class="n">page_size</span> <span class="o">=</span> <span class="mi">10</span>
|
|
|
|
<span class="c1"># Extract cursor from request params</span>
|
|
<span class="n">cursor</span> <span class="o">=</span> <span class="n">request</span><span class="o">.</span><span class="n">params</span><span class="o">.</span><span class="n">cursor</span> <span class="k">if</span> <span class="n">request</span><span class="o">.</span><span class="n">params</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span> <span class="k">else</span> <span class="kc">None</span>
|
|
|
|
<span class="c1"># Parse cursor to get offset</span>
|
|
<span class="n">start</span> <span class="o">=</span> <span class="mi">0</span> <span class="k">if</span> <span class="n">cursor</span> <span class="ow">is</span> <span class="kc">None</span> <span class="k">else</span> <span class="nb">int</span><span class="p">(</span><span class="n">cursor</span><span class="p">)</span>
|
|
<span class="n">end</span> <span class="o">=</span> <span class="n">start</span> <span class="o">+</span> <span class="n">page_size</span>
|
|
|
|
<span class="c1"># Get page of resources</span>
|
|
<span class="n">page_items</span> <span class="o">=</span> <span class="p">[</span>
|
|
<span class="n">types</span><span class="o">.</span><span class="n">Resource</span><span class="p">(</span><span class="n">uri</span><span class="o">=</span><span class="n">AnyUrl</span><span class="p">(</span><span class="sa">f</span><span class="s2">"resource://items/</span><span class="si">{</span><span class="n">item</span><span class="si">}</span><span class="s2">"</span><span class="p">),</span> <span class="n">name</span><span class="o">=</span><span class="n">item</span><span class="p">,</span> <span class="n">description</span><span class="o">=</span><span class="sa">f</span><span class="s2">"Description for </span><span class="si">{</span><span class="n">item</span><span class="si">}</span><span class="s2">"</span><span class="p">)</span>
|
|
<span class="k">for</span> <span class="n">item</span> <span class="ow">in</span> <span class="n">ITEMS</span><span class="p">[</span><span class="n">start</span><span class="p">:</span><span class="n">end</span><span class="p">]</span>
|
|
<span class="p">]</span>
|
|
|
|
<span class="c1"># Determine next cursor</span>
|
|
<span class="n">next_cursor</span> <span class="o">=</span> <span class="nb">str</span><span class="p">(</span><span class="n">end</span><span class="p">)</span> <span class="k">if</span> <span class="n">end</span> <span class="o"><</span> <span class="nb">len</span><span class="p">(</span><span class="n">ITEMS</span><span class="p">)</span> <span class="k">else</span> <span class="kc">None</span>
|
|
|
|
<span class="k">return</span> <span class="n">types</span><span class="o">.</span><span class="n">ListResourcesResult</span><span class="p">(</span><span class="n">resources</span><span class="o">=</span><span class="n">page_items</span><span class="p">,</span> <span class="n">nextCursor</span><span class="o">=</span><span class="n">next_cursor</span><span class="p">)</span>
|
|
</code></pre></div>
|
|
<p><em>Full example: <a href="https://github.com/modelcontextprotocol/python-sdk/blob/v1.x/examples/snippets/servers/pagination_example.py">examples/snippets/servers/pagination_example.py</a></em></p>
|
|
<!-- /snippet-source -->
|
|
|
|
<h3 id="client-side-consumption">Client-side Consumption</h3>
|
|
<!-- snippet-source examples/snippets/clients/pagination_client.py -->
|
|
<div class="language-python highlight"><pre><span></span><code><span class="sd">"""</span>
|
|
<span class="sd">Example of consuming paginated MCP endpoints from a client.</span>
|
|
<span class="sd">"""</span>
|
|
|
|
<span class="kn">import</span><span class="w"> </span><span class="nn">asyncio</span>
|
|
|
|
<span class="kn">from</span><span class="w"> </span><span class="nn">mcp.client.session</span><span class="w"> </span><span class="kn">import</span> <span class="n">ClientSession</span>
|
|
<span class="kn">from</span><span class="w"> </span><span class="nn">mcp.client.stdio</span><span class="w"> </span><span class="kn">import</span> <span class="n">StdioServerParameters</span><span class="p">,</span> <span class="n">stdio_client</span>
|
|
<span class="kn">from</span><span class="w"> </span><span class="nn">mcp.types</span><span class="w"> </span><span class="kn">import</span> <span class="n">PaginatedRequestParams</span><span class="p">,</span> <span class="n">Resource</span>
|
|
|
|
|
|
<span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">list_all_resources</span><span class="p">()</span> <span class="o">-></span> <span class="kc">None</span><span class="p">:</span>
|
|
<span class="w"> </span><span class="sd">"""Fetch all resources using pagination."""</span>
|
|
<span class="k">async</span> <span class="k">with</span> <span class="n">stdio_client</span><span class="p">(</span><span class="n">StdioServerParameters</span><span class="p">(</span><span class="n">command</span><span class="o">=</span><span class="s2">"uv"</span><span class="p">,</span> <span class="n">args</span><span class="o">=</span><span class="p">[</span><span class="s2">"run"</span><span class="p">,</span> <span class="s2">"mcp-simple-pagination"</span><span class="p">]))</span> <span class="k">as</span> <span class="p">(</span>
|
|
<span class="n">read</span><span class="p">,</span>
|
|
<span class="n">write</span><span class="p">,</span>
|
|
<span class="p">):</span>
|
|
<span class="k">async</span> <span class="k">with</span> <span class="n">ClientSession</span><span class="p">(</span><span class="n">read</span><span class="p">,</span> <span class="n">write</span><span class="p">)</span> <span class="k">as</span> <span class="n">session</span><span class="p">:</span>
|
|
<span class="k">await</span> <span class="n">session</span><span class="o">.</span><span class="n">initialize</span><span class="p">()</span>
|
|
|
|
<span class="n">all_resources</span><span class="p">:</span> <span class="nb">list</span><span class="p">[</span><span class="n">Resource</span><span class="p">]</span> <span class="o">=</span> <span class="p">[]</span>
|
|
<span class="n">cursor</span> <span class="o">=</span> <span class="kc">None</span>
|
|
|
|
<span class="k">while</span> <span class="kc">True</span><span class="p">:</span>
|
|
<span class="c1"># Fetch a page of resources</span>
|
|
<span class="n">result</span> <span class="o">=</span> <span class="k">await</span> <span class="n">session</span><span class="o">.</span><span class="n">list_resources</span><span class="p">(</span><span class="n">params</span><span class="o">=</span><span class="n">PaginatedRequestParams</span><span class="p">(</span><span class="n">cursor</span><span class="o">=</span><span class="n">cursor</span><span class="p">))</span>
|
|
<span class="n">all_resources</span><span class="o">.</span><span class="n">extend</span><span class="p">(</span><span class="n">result</span><span class="o">.</span><span class="n">resources</span><span class="p">)</span>
|
|
|
|
<span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">"Fetched </span><span class="si">{</span><span class="nb">len</span><span class="p">(</span><span class="n">result</span><span class="o">.</span><span class="n">resources</span><span class="p">)</span><span class="si">}</span><span class="s2"> resources"</span><span class="p">)</span>
|
|
|
|
<span class="c1"># Check if there are more pages</span>
|
|
<span class="k">if</span> <span class="n">result</span><span class="o">.</span><span class="n">nextCursor</span><span class="p">:</span>
|
|
<span class="n">cursor</span> <span class="o">=</span> <span class="n">result</span><span class="o">.</span><span class="n">nextCursor</span>
|
|
<span class="k">else</span><span class="p">:</span>
|
|
<span class="k">break</span>
|
|
|
|
<span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">"Total resources: </span><span class="si">{</span><span class="nb">len</span><span class="p">(</span><span class="n">all_resources</span><span class="p">)</span><span class="si">}</span><span class="s2">"</span><span class="p">)</span>
|
|
|
|
|
|
<span class="k">if</span> <span class="vm">__name__</span> <span class="o">==</span> <span class="s2">"__main__"</span><span class="p">:</span>
|
|
<span class="n">asyncio</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="n">list_all_resources</span><span class="p">())</span>
|
|
</code></pre></div>
|
|
<p><em>Full example: <a href="https://github.com/modelcontextprotocol/python-sdk/blob/v1.x/examples/snippets/clients/pagination_client.py">examples/snippets/clients/pagination_client.py</a></em></p>
|
|
<!-- /snippet-source -->
|
|
|
|
<h3 id="key-points">Key Points</h3>
|
|
<ul>
|
|
<li><strong>Cursors are opaque strings</strong> - the server defines the format (numeric offsets, timestamps, etc.)</li>
|
|
<li><strong>Return <code>nextCursor=None</code></strong> when there are no more pages</li>
|
|
<li><strong>Backward compatible</strong> - clients that don't support pagination will still work (they'll just get the first page)</li>
|
|
<li><strong>Flexible page sizes</strong> - Each endpoint can define its own page size based on data characteristics</li>
|
|
</ul>
|
|
<p>See the <a href="https://github.com/modelcontextprotocol/python-sdk/tree/v1.x/examples/servers/simple-pagination">simple-pagination example</a> for a complete implementation.</p>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</article>
|
|
</div>
|
|
|
|
|
|
<script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script>
|
|
|
|
<script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script>
|
|
</div>
|
|
|
|
</main>
|
|
|
|
<footer class="md-footer">
|
|
|
|
<div class="md-footer-meta md-typeset">
|
|
<div class="md-footer-meta__inner md-grid">
|
|
<div class="md-copyright">
|
|
|
|
|
|
Made with
|
|
<a href="https://squidfunk.github.io/mkdocs-material/" target="_blank" rel="noopener">
|
|
Material for MkDocs
|
|
</a>
|
|
|
|
</div>
|
|
|
|
</div>
|
|
</div>
|
|
</footer>
|
|
|
|
</div>
|
|
<div class="md-dialog" data-md-component="dialog">
|
|
<div class="md-dialog__inner md-typeset"></div>
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<script id="__config" type="application/json">{"base": "..", "features": ["search.suggest", "search.highlight", "content.tabs.link", "content.code.annotate", "content.code.copy", "content.code.select", "navigation.path", "navigation.indexes", "navigation.sections", "navigation.tracking", "toc.follow"], "search": "../assets/javascripts/workers/search.973d3a69.min.js", "tags": null, "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}, "version": null}</script>
|
|
|
|
|
|
<script src="../assets/javascripts/bundle.92b07e13.min.js"></script>
|
|
|
|
|
|
|
|
<script id="init-glightbox">const lightbox = GLightbox({"touchNavigation": true, "loop": false, "zoomable": true, "draggable": true, "openEffect": "zoom", "closeEffect": "zoom", "slideEffect": "slide"});
|
|
document$.subscribe(()=>{ lightbox.reload(); });
|
|
</script></body></html> |