![](data:image/svg+xml, %3Csvg xmlns='http://www.w3.org/2000/svg' height='64' class='font-weight-bold' style='font: 600 30.11764705882353px "SegoeUI", Arial' width='64'%3E%3Ccircle fill='hsl(9.6, 33%, 10%)' cx='32' cy='32' r='32' /%3E%3Ctext x='50%25' y='55%25' dominant-baseline='middle' text-anchor='middle' fill='%23FFF' %3ES%3C/text%3E%3C/svg%3E)
Microsoft Copilot | Microsoft 365 Copilot | Development
Building and customizing solutions using Microsoft 365 Copilot APIs and tools
This behavior matches a citation-mapping problem, not the expected clickable citation experience.
For MCP or API-based content, clickable citations require the tool response to expose an end-user-openable URL and for Copilot to know where that URL is in the response. This is done through response_semantics, specifically:
-
data_pathmust point to the correct array or object. -
propertiesmust map the citation fields such astitle,subtitle, andurl.
If this is skipped or misconfigured, Copilot can still show a citation, but it may only appear as a representative pill/icon instead of a clickable source. Missing or non-empty url values are a common reason citations are not clickable.
Because the displayed source is truncated raw JSON like {"results":[{"title":..., the most likely issue is that Copilot is receiving the MCP payload as text instead of resolving the citable items correctly. The first checks are:
- Verify
data_pathpoints to the actual results node.- If the response shape is
{ "results": [ ... ] }, use$.results. - If the response is MCP-style nested like
{ "content": [ { "results": [ ... ] } ] }, use$.content[0].results. - If the MCP
textfield contains stringified JSON, confirm the parser is unwrapping it as expected.
- If the response shape is
- Verify each result item has a non-empty URL field.
- If
urlis missing, the citation is not clickable. - Copilot can infer common aliases such as
webUrl,href, orlinkwhen explicit mappings are absent.
- If
- If explicit
response_semanticsis used, verify it is declared per function inside that function’scapabilities, not at the plugin root. - Flatten the response if it contains deeply nested arrays.
- The documented guidance is that multi-level nested arrays are more likely to fail silently.
- If the tool surface is dynamic, rely on the zero-config fallback only when the response uses recognized aliases such as:
- results array:
results,items,data - URL:
url,webUrl,href,link - title:
title,name - subtitle:
subtitle,description,summary
- results array:
On the specific questions:
- It is not the documented expected behavior for a correctly mapped MCP citation. The documented behavior is clickable citations when an openable URL is returned and mapped correctly.
- Yes. The required configuration is
response_semanticswith the correctdata_pathandproperties, unless the response shape is compatible with dynamic response semantics inference. - It is most consistent with how the MCP response is being returned or mapped for citation extraction, especially if the
resultsobject is being surfaced as raw text instead of parsed citation items. - Recommended workaround:
- Return a flat results array.
- Ensure each item includes a canonical source URL.
- Add explicit
response_semanticsrather than relying on inference. - Avoid using an Adaptive Card unless a custom citation layout or extra actions are required; response semantics alone is sufficient for clickable citations.
A practical validation path is:
- Capture the raw MCP JSON response.
- Confirm whether the citable items are in
resultsor insidecontent[0].textas stringified JSON. - Set
data_pathto the exact node containing the citation items. - Map
titleandurlexplicitly. - Retest and confirm the Sources panel shows the document title instead of the raw JSON blob.