Python: Add models for the MCP server SDKs (mcp, fastmcp)

Author: Alex-Hofer

python/ql/lib/change-notes/2026-09-30-mcp-models.md

@@ -0,0 +1,4 @@
+---
+category: minorAnalysis
+---
+* Added modeling of the `mcp` (the official Model Context Protocol SDK) and `fastmcp` PyPI packages. The parameters of MCP tool, resource and prompt handlers, the HTTP headers that `fastmcp` handlers read through `get_http_headers()` or `get_http_request()`, and the bearer token that token verifiers (`verify_token`) and `get_access_token()` receive, are now sources of the `remote` threat model.

python/ql/lib/semmle/python/frameworks/fastmcp.model.yml

@@ -0,0 +1,35 @@
+extensions:
+  - addsTo:
+      pack: codeql/python-all
+      extensible: sourceModel
+    data:
+      # `fastmcp` (PyPI), a standalone MCP server framework. The parameters of tool, resource and
+      # prompt handlers are chosen by the MCP client; `tool` and `prompt` also work without parentheses.
+      - ['fastmcp.FastMCP', 'Member[tool,prompt].Argument[0,name_or_fn:].Parameter[any]', 'remote']
+      - ['fastmcp.FastMCP', 'Member[tool,resource,prompt].ReturnValue.Argument[0].Parameter[any]', 'remote']
+      - ['fastmcp.FastMCP', 'Member[add_tool].Argument[0,tool:].Parameter[any]', 'remote']
+      - ['fastmcp.FastMCP', 'Member[add_prompt].Argument[0,prompt:].Parameter[any]', 'remote']
+      - ['fastmcp.tools.Tool!', 'Member[from_function].Argument[0,fn:].Parameter[any]', 'remote']
+      - ['fastmcp', 'Member[tools].Member[tool].Argument[0,name_or_fn:].Parameter[any]', 'remote']
+      - ['fastmcp', 'Member[tools].Member[tool].ReturnValue.Argument[0].Parameter[any]', 'remote']
+      # The HTTP headers of the transport.
+      - ['fastmcp', 'Member[server].Member[dependencies].Member[get_http_headers].ReturnValue', 'remote']
+      - ['fastmcp', 'Member[server].Member[dependencies].Member[get_http_request].ReturnValue.Member[headers]', 'remote']
+      # The bearer token of the Authorization header reaches token verifiers and the access-token helper.
+      - ['fastmcp.server.auth.TokenVerifier!', 'Subclass.Member[verify_token].Parameter[0,token:]', 'remote']
+      - ['fastmcp.server.auth.AuthProvider!', 'Subclass.Member[verify_token].Parameter[0,token:]', 'remote']
+      - ['fastmcp', 'Member[server].Member[dependencies].Member[get_access_token].ReturnValue.Member[token]', 'remote']
+
+  - addsTo:
+      pack: codeql/python-all
+      extensible: typeModel
+    data:
+      # The classes are re-exported; instances of any import path are instances of the class.
+      - ['fastmcp.FastMCP!', 'fastmcp', 'Member[server].Member[FastMCP]']
+      - ['fastmcp.FastMCP!', 'fastmcp', 'Member[server].Member[server].Member[FastMCP]']
+      - ['fastmcp.FastMCP', 'fastmcp.FastMCP!', 'Instance']
+      - ['fastmcp.tools.Tool!', 'fastmcp', 'Member[tools].Member[FunctionTool]']
+      - ['fastmcp.tools.Tool!', 'fastmcp', 'Member[tools].Member[base].Member[Tool]']
+      - ['fastmcp.tools.Tool!', 'fastmcp', 'Member[tools].Member[function_tool].Member[FunctionTool]']
+      - ['fastmcp.server.auth.TokenVerifier!', 'fastmcp', 'Member[server].Member[auth].Member[auth].Member[TokenVerifier]']
+      - ['fastmcp.server.auth.AuthProvider!', 'fastmcp', 'Member[server].Member[auth].Member[auth].Member[AuthProvider]']

python/ql/lib/semmle/python/frameworks/mcp.model.yml

@@ -0,0 +1,33 @@
+extensions:
+  - addsTo:
+      pack: codeql/python-all
+      extensible: sourceModel
+    data:
+      # `mcp`, the official Model Context Protocol SDK. The parameters of tool, resource and prompt
+      # handlers are chosen by the MCP client, that is by an LLM or by anyone who can reach the server.
+      # `FastMCP` (1.x) was renamed to `MCPServer` (2.x).
+      - ['mcp.server.fastmcp.FastMCP', 'Member[tool,resource,prompt].ReturnValue.Argument[0].Parameter[any]', 'remote']
+      - ['mcp.server.fastmcp.FastMCP', 'Member[add_tool].Argument[0,fn:].Parameter[any]', 'remote']
+      - ['mcp.server.mcpserver.MCPServer', 'Member[tool,resource,prompt].ReturnValue.Argument[0].Parameter[any]', 'remote']
+      - ['mcp.server.mcpserver.MCPServer', 'Member[add_tool].Argument[0,fn:].Parameter[any]', 'remote']
+      # The low-level server: decorators in 1.x, constructor handlers taking `(ctx, params)` in 2.x.
+      - ['mcp.server.lowlevel.Server', 'Member[call_tool,read_resource,get_prompt].ReturnValue.Argument[0].Parameter[any]', 'remote']
+      - ['mcp.server.lowlevel.Server!', 'Argument[on_call_tool:,on_get_prompt:].Parameter[1].Member[arguments]', 'remote']
+      - ['mcp.server.lowlevel.Server!', 'Argument[on_read_resource:].Parameter[1].Member[uri]', 'remote']
+      # The bearer token of the Authorization header reaches token verifiers and the access-token helper.
+      - ['mcp.server.auth.provider.TokenVerifier!', 'Subclass.Member[verify_token].Parameter[0,token:]', 'remote']
+      - ['mcp', 'Member[server].Member[auth].Member[middleware].Member[auth_context].Member[get_access_token].ReturnValue.Member[token]', 'remote']
+
+  - addsTo:
+      pack: codeql/python-all
+      extensible: typeModel
+    data:
+      # The classes are re-exported; instances of any import path are instances of the class.
+      - ['mcp.server.fastmcp.FastMCP!', 'mcp', 'Member[server].Member[fastmcp].Member[server].Member[FastMCP]']
+      - ['mcp.server.fastmcp.FastMCP', 'mcp.server.fastmcp.FastMCP!', 'Instance']
+      - ['mcp.server.mcpserver.MCPServer!', 'mcp', 'Member[server].Member[MCPServer]']
+      - ['mcp.server.mcpserver.MCPServer!', 'mcp', 'Member[server].Member[mcpserver].Member[server].Member[MCPServer]']
+      - ['mcp.server.mcpserver.MCPServer', 'mcp.server.mcpserver.MCPServer!', 'Instance']
+      - ['mcp.server.lowlevel.Server!', 'mcp', 'Member[server].Member[Server]']
+      - ['mcp.server.lowlevel.Server!', 'mcp', 'Member[server].Member[lowlevel].Member[server].Member[Server]']
+      - ['mcp.server.lowlevel.Server', 'mcp.server.lowlevel.Server!', 'Instance']

python/ql/test/library-tests/frameworks/fastmcp/MaDTest.expected

@@ -0,0 +1,2 @@
+import python
+import experimental.meta.MaDTest

python/ql/test/library-tests/frameworks/fastmcp/MaDTest.ql

@@ -0,0 +1,122 @@
+from fastmcp import FastMCP
+from fastmcp.server import FastMCP as ServerFastMCP
+from fastmcp.server.server import FastMCP as ModuleFastMCP
+from fastmcp.server.auth import AuthProvider, TokenVerifier
+from fastmcp.server.auth.auth import TokenVerifier as ModuleTokenVerifier
+from fastmcp.server.dependencies import get_access_token, get_http_headers, get_http_request
+from fastmcp.tools import FunctionTool, Tool, tool
+from fastmcp.tools.base import Tool as BaseTool
+from fastmcp.tools.function_tool import FunctionTool as ModuleFunctionTool
+
+app = FastMCP("test")
+server_app = ServerFastMCP("test")
+module_app = ModuleFastMCP("test")
+
+
+@app.tool
+def bare(command): # $ mad-source__remote=command
+    return command
+
+
+@server_app.tool(name="exec")
+def called(command): # $ mad-source__remote=command
+    return command
+
+
+@module_app.resource("files://{path}")
+def resource(path): # $ mad-source__remote=path
+    return path
+
+
+@app.prompt
+def bare_prompt(topic): # $ mad-source__remote=topic
+    return topic
+
+
+@app.prompt()
+def called_prompt(topic, style="short"): # $ mad-source__remote=topic mad-source__remote=style
+    return topic + style
+
+
+def added(command): # $ mad-source__remote=command
+    return command
+
+
+app.add_tool(added)
+
+
+def added_prompt(topic): # $ mad-source__remote=topic
+    return topic
+
+
+app.add_prompt(prompt=added_prompt)
+
+
+def via_tool(url): # $ mad-source__remote=url
+    return url
+
+
+def via_function_tool(url): # $ mad-source__remote=url
+    return url
+
+
+def via_base_tool(url): # $ mad-source__remote=url
+    return url
+
+
+def via_module_function_tool(url): # $ mad-source__remote=url
+    return url
+
+
+Tool.from_function(via_tool)
+FunctionTool.from_function(via_function_tool)
+BaseTool.from_function(fn=via_base_tool)
+ModuleFunctionTool.from_function(via_module_function_tool)
+
+
+@tool
+def standalone(command): # $ mad-source__remote=command
+    return command
+
+
+@tool()
+def standalone_called(command): # $ mad-source__remote=command
+    return command
+
+
+@app.tool
+def forward_header():
+    return get_http_headers()["x-target"] # $ mad-source__remote=get_http_headers()
+
+
+@app.tool
+def forward_request_header():
+    return get_http_request().headers["x-target"] # $ mad-source__remote=get_http_request().headers
+
+
+def not_registered(value):
+    return value
+
+
+class Verifier(TokenVerifier):
+    async def verify_token(self, token): # $ mad-source__remote=token
+        return token
+
+
+class ModuleVerifier(ModuleTokenVerifier):
+    async def verify_token(self, token): # $ mad-source__remote=token
+        return token
+
+
+class Provider(AuthProvider):
+    async def verify_token(self, token): # $ mad-source__remote=token
+        return token
+
+
+class NotAVerifier:
+    async def verify_token(self, token):
+        return token
+
+
+def session():
+    return get_access_token().token # $ mad-source__remote=get_access_token().token

python/ql/test/library-tests/frameworks/fastmcp/test.py

@@ -0,0 +1,2 @@
+import python
+import experimental.meta.MaDTest

python/ql/test/library-tests/frameworks/mcp/MaDTest.expected

@@ -0,0 +1,16 @@
+from mcp.server.auth.middleware.auth_context import get_access_token
+from mcp.server.auth.provider import TokenVerifier
+
+
+class Verifier(TokenVerifier):
+    async def verify_token(self, token): # $ mad-source__remote=token
+        return token
+
+
+class NotAVerifier:
+    async def verify_token(self, token):
+        return token
+
+
+def session():
+    return get_access_token().token # $ mad-source__remote=get_access_token().token

python/ql/test/library-tests/frameworks/mcp/MaDTest.ql

@@ -0,0 +1,47 @@
+from mcp.server.fastmcp import FastMCP
+from mcp.server.fastmcp.server import FastMCP as ModuleFastMCP
+
+server = FastMCP("test")
+other = ModuleFastMCP("test")
+
+
+@server.tool()
+def run(command): # $ mad-source__remote=command
+    return command
+
+
+@other.resource("notes://{name}")
+def note(name): # $ mad-source__remote=name
+    return name
+
+
+@server.prompt()
+def summarize(topic, style="short"): # $ mad-source__remote=topic mad-source__remote=style
+    return topic + style
+
+
+def fetch(url): # $ mad-source__remote=url
+    return url
+
+
+other.add_tool(fn=fetch)
+
+
+def register(app: FastMCP):
+    @app.tool()
+    def remove(path): # $ mad-source__remote=path
+        return path
+
+
+class Service:
+    def __init__(self):
+        self.mcp = FastMCP("test")
+
+    def register(self):
+        @self.mcp.tool()
+        def lookup(host): # $ mad-source__remote=host
+            return host
+
+
+def not_registered(value):
+    return value