stackexchange-mcp-server

Search Stack Exchange Questions

stackexchange_search_questions

Read-onlyIdempotent

Search questions across a Stack Exchange site. Returns ranked questions with title, score, answer count, accepted status, tags, ask and last-activity dates, and a short excerpt of the question body — not the full body. Results supply question_id values for stackexchange_get_thread, which fetches the full question body and all answers. Results past the pageSize cap are reachable with the page parameter. Use the site parameter to target a specific community (e.g. "stackoverflow", "superuser", "unix"); call stackexchange_list_sites to discover valid site values.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`page`	No	Page of results to return, 1-based (default 1). Page 2 with pageSize 10 returns results 11–20. Each page is a separate upstream call and costs one API quota unit, which matters on the keyless 300/day tier. Without STACKEXCHANGE_API_KEY, Stack Exchange refuses any page above 25.
`site`	No	Stack Exchange site to search — use the api_site_parameter value (e.g. "stackoverflow", "superuser", "serverfault"). Defaults to "stackoverflow". Call stackexchange_list_sites to discover valid values.	stackoverflow
`sort`	No	Result ordering: "relevance" (default, best match), "votes" (highest score first), "activity" (most recently active), "newest" (most recently created).	relevance
`tags`	No	Filter results to questions with all specified tags.
`query`	Yes	Full-text search query (e.g. "python async generator send value").
`minScore`	No	Minimum question score — excludes questions with lower scores. Setting minScore orders results by score (votes), which may differ from the requested sort.
`pageSize`	No	Number of results to return (1–30, default 10).
`acceptedOnly`	No	When true, return only questions that have an accepted answer.

Output Schema

TableJSON Schema

Name	Required	Description
`cap`	No	The pageSize cap applied to this request.
`page`	No	The 1-based page these results came from — 1 when the input omitted page.
`error`	No	Present when the call failed. Absent on success.
`shown`	No	Number of results returned.
`notice`	No	Actionable guidance when results are empty or filtered.
`quotaMax`	No	Maximum API quota calls per day (300 keyless, ~10,000 with API key).
`questions`	No	Questions matching the search query, ordered by the specified sort.
`truncated`	No	True when results were capped at pageSize.
`attribution`	No	Content license notice. Stack Exchange content is licensed under CC BY-SA 4.0 and requires attribution.
`quotaRemaining`	No	Remaining API quota calls for the current day.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedSep 10, 2026

changedOutput schema / properties / questions / items / properties / excerpt / description

Previous value: -"Opening prose of the question body, trimmed to roughly 300 characters and ending in \"…\" when cut. Code blocks are omitted; absent when the question body is nothing but code."New value: +"Opening prose of the question body, trimmed to roughly 300 characters and ending in \"…\" when cut. Code blocks and markdown structure are omitted; absent when the question body is nothing but code."

Changed6 schema fields changedSep 10, 2026

addedInput schema / properties / page

Added value: +{
+  "default": 1,
+  "description": "Page of results to return, 1-based (default 1). Page 2 with pageSize 10 returns results 11–20. Each page is a separate upstream call and costs one API quota unit, which matters on the keyless 300/day tier. Without STACKEXCHANGE_API_KEY, Stack Exchange refuses any page above 25.",
+  "maximum": 9007199254740991,
+  "minimum": 1,
+  "type": "integer"
+}

changedOutput schema / anyOf

Previous value: -[
-  {
-    "not": {
-      "required": [
-        "error"
-      ]
-    },
-    "required": [
-      "questions",
-      "attribution",
-      "quotaRemaining",
-      "quotaMax"
-    ]
-  },
-  {
-    "required": [
-      "error"
-    ]
-  }
-]New value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "questions",
+      "page",
+      "attribution",
+      "quotaRemaining",
+      "quotaMax"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `invalid_site`: The provided site value is not a valid Stack Exchange network site identifier. `invalid_parameter`: Stack Exchange rejected a request parameter and named the field rather than reporting a bad site. `quota_exceeded`: The Stack Exchange API quota_remaining has reached 0. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `invalid_site`: The provided site value is not a valid Stack Exchange network site identifier. `invalid_parameter`: Stack Exchange rejected a request parameter and named the field rather than reporting a bad site. `quota_exceeded`: The Stack Exchange API quota_remaining has reached 0. `paging_depth_limit`: Stack Exchange refused the requested page because paging above page 25 needs a key. `invalid_api_key`: Stack Exchange does not recognize the API key this server is configured with. `upstream_unavailable`: Stack Exchange answered with a body that is not the expected JSON envelope. Other values are possible when a failure originates below the handler."

changedOutput schema / properties / error / properties / data / properties / reason / examples

Previous value: -[
-  "invalid_site",
-  "invalid_parameter",
-  "quota_exceeded"
-]New value: +[
+  "invalid_site",
+  "invalid_parameter",
+  "quota_exceeded",
+  "paging_depth_limit",
+  "invalid_api_key",
+  "upstream_unavailable"
+]

addedOutput schema / properties / page

Added value: +{
+  "description": "The 1-based page these results came from — 1 when the input omitted page.",
+  "maximum": 9007199254740991,
+  "minimum": -9007199254740991,
+  "type": "integer"
+}

changedOutput schema / properties / questions / items / properties / excerpt / description

Previous value: -"Short text excerpt from the question when available."New value: +"Opening prose of the question body, trimmed to roughly 300 characters and ending in \"…\" when cut. Code blocks are omitted; absent when the question body is nothing but code."

Changed5 schema fields changedSep 10, 2026

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `invalid_site`: The provided site value is not a valid Stack Exchange network site identifier. `quota_exceeded`: The Stack Exchange API quota_remaining has reached 0. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `invalid_site`: The provided site value is not a valid Stack Exchange network site identifier. `invalid_parameter`: Stack Exchange rejected a request parameter and named the field rather than reporting a bad site. `quota_exceeded`: The Stack Exchange API quota_remaining has reached 0. Other values are possible when a failure originates below the handler."

changedOutput schema / properties / error / properties / data / properties / reason / examples

Previous value: -[
-  "invalid_site",
-  "quota_exceeded"
-]New value: +[
+  "invalid_site",
+  "invalid_parameter",
+  "quota_exceeded"
+]

changedOutput schema / properties / questions / items / description

Previous value: -"A Stack Exchange question with score, answer count, tags, and optional excerpt."New value: +"A Stack Exchange question with score, answer count, tags, dates, and optional excerpt."

addedOutput schema / properties / questions / items / properties / creationDate

Added value: +{
+  "description": "ISO 8601 timestamp of when the question was asked — use it to judge whether the advice is still current.",
+  "type": "string"
+}

addedOutput schema / properties / questions / items / properties / lastActivityDate

Added value: +{
+  "description": "ISO 8601 timestamp of the most recent activity on the question (edit, answer, or comment).",
+  "type": "string"
+}

Changed6 schema fields changedAug 22, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedInput schema / additionalProperties
```
Added value: +false
```

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedOutput schema / anyOf

Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "questions",
+      "attribution",
+      "quotaRemaining",
+      "quotaMax"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

addedOutput schema / properties / error

Added value: +{
+  "additionalProperties": {},
+  "description": "Present when the call failed. Absent on success.",
+  "properties": {
+    "code": {
+      "description": "JSON-RPC error code for this failure.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "data": {
+      "additionalProperties": {},
+      "properties": {
+        "reason": {
+          "description": "Machine-readable failure mode. Declared by this tool: `invalid_site`: The provided site value is not a valid Stack Exchange network site identifier. `quota_exceeded`: The Stack Exchange API quota_remaining has reached 0. Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "invalid_site",
+            "quota_exceeded"
+          ],
+          "type": "string"
+        },
+        "recovery": {
+          "additionalProperties": {},
+          "description": "Actionable next step for the caller.",
+          "properties": {
+            "hint": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "hint"
+          ],
+          "type": "object"
+        },
+        "retryable": {
+          "description": "Whether retrying may succeed.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable description of what went wrong.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ],
+  "type": "object"
+}

removedOutput schema / required

Removed value: -[
-  "questions",
-  "attribution",
-  "quotaRemaining",
-  "quotaMax"
-]

Changed1 schema field changedJul 17, 2026

changedInput schema / properties / minScore / description

Previous value: -"Minimum question score — excludes questions with lower scores."New value: +"Minimum question score — excludes questions with lower scores. Setting minScore orders results by score (votes), which may differ from the requested sort."

Changed3 schema fields changedJun 13, 2026

addedOutput schema / properties / cap

Added value: +{
+  "description": "The pageSize cap applied to this request.",
+  "type": "number"
+}

addedOutput schema / properties / shown

Added value: +{
+  "description": "Number of results returned.",
+  "type": "number"
+}

addedOutput schema / properties / truncated

Added value: +{
+  "description": "True when results were capped at pageSize.",
+  "type": "boolean"
+}

First observedJun 7, 2026

TDQS

A4.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the readOnlyHint/idempotentHint annotations, the description discloses that results contain excerpts only, that pagination costs an additional API quota call, that page above 25 is unavailable without a key, and that question_id is the link to the sibling tool. This is far more than the annotations convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Four tight sentences: what it returns, what it omits, how results feed the sibling tool, and how to page/site. Every sentence earns its place and the most decision-relevant facts are front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only search tool, the description fully covers return shape, exclusions, pagination, quota cost, site targeting, and inter-tool relationships. Nothing needed to call it safely is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema already provides 100% parameter coverage with descriptions for default, range, and meaning.utils. The description adds cross-parameter context (page quota cost, pageSize cap) and clarifies the site enum via list_sites. This exceeds the baseline but does not need to repeat the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a clear verb-resource pair: 'Search questions across a Stack Exchange site.' It lists the returned fields (score, answer count, accepted status, tags, dates, excerpt), explicitly states what it does not return (full body), and frames the result as a discovery tool. It clearly differs from the referenced get_thread tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly routes the agent: use this tool for ranked search results and take question_id to stackexchange_get_thread when the full body is needed. It also tells the agent to use stackexchange_list_sites for valid site values. These are concrete, actionable selection cues.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All stackexchange-mcp-server tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.