---
schema_version: "1"
id: 6ef581bb16c42a04a4289d2584f2dace75950ad2c840479865ca2888cc912cb3
title: MCP Tool Response Schemas and Agent Design
collection: admin
version: current
locale: en-us
portal_url: https://docs.salesforce.com/admin/current/en-us/ai/264-0-0/agent_mcp_tool_action_design.md
canonical_url: https://help.salesforce.com/s/articleView?id=ai.agent_mcp_tool_action_design.htm&release=264.0.0&type=5
source_site: help.salesforce.com
content_type: documentation
content_hash: 02458d7b5be4593f9ceb14a091c53e9d6ebfbf84b88abe4f153ff1f456894d76
description: MCP server tools are added to your agent as agent actions that reference the server tool (MCP tool actions) and can be used just like other agent actions. However, not all valid MCP response schemas are fully supported in Agentforce Builder. As you build your agent, plan for differences in variable mapping, action chaining, and input and output rendering. Complex responses may require simpler agent design patterns.
products:
  - Agentforce
  - Cross Cloud
release: "264"
---
# MCP Tool Response Schemas and Agent Design

MCP server tools are added to your agent as agent actions that reference the server tool (MCP tool actions) and can be used just like other agent actions. However, not all valid MCP response schemas are fully supported in Agentforce Builder. As you build your agent, plan for differences in variable mapping, action chaining, and input and output rendering. Complex responses may require simpler agent design patterns.

### Required Editions

<table class="slds-table slds-table_bordered slds-max-medium-table_stacked slds-m-bottom_small edition"><colgroup><col></colgroup><tbody><tr class=""><td class="slds-cell-wrap" style="vertical-align:top;">Available in: Lightning Experience</td></tr><tr class=""><td class="slds-cell-wrap" style="vertical-align:top;">Available in: <strong>Enterprise</strong>, <strong>Performance</strong>, <strong>Unlimited</strong>, and <strong>Developer</strong> Editions. <a href="https://help.salesforce.com/s/articleView?id=ai.agent_setup_explore_types.htm&amp;release=264.0.0&amp;type=5" title="Learn about agent types and default templates for specific clouds and common use cases.">Required add-on licenses vary by agent type.</a></td></tr></tbody></table>

## Supported JSON Responses

Agentforce Builder support is strongest for primitive values and shallow field access, so choose MCP server tools with simple structured JSON responses or adjust your responses to expose important values as primitive fields or simple top-level fields, where possible. Supported JSON responses include top-level objects, top-level object properties, and top-level arrays of objects. More complex shapes aren’t currently supported end to end, including nested properties, arrays of objects, and dynamic object payloads.

Like other agent actions, if an MCP tool action input or output contains multiple levels of properties (for example, nested properties, arrays of objects, or dynamic object payloads), the agent can only use the first level of properties in action inputs, action outputs, and variable mappings.

<table class="slds-table slds-table_bordered slds-max-medium-table_stacked slds-m-bottom_small ">
        <colgroup>
          <col style="width:33.33333333333333%">
          <col style="width:66.66666666666666%">
        </colgroup>
        <thead class="slds-text-title_caps ">
          <tr class="">
            <th scope="col" class="slds-cell-wrap" style="vertical-align:top;" id="d101459e87">Supported JSON Responses</th>
            <th scope="col" class="slds-cell-wrap" style="vertical-align:top;" id="d101459e90">Examples</th>
          </tr>
        </thead>
        <tbody>
          <tr class="">
            <td data-label="Supported JSON Responses" class="slds-cell-wrap" style="vertical-align:top;" headers="d101459e87 ">Object types with no properties field</td>

            <td data-label="Examples" class="slds-cell-wrap" style="vertical-align:top;" headers="d101459e90 ">
              <pre class="line-numbers slds-box slds-box_x-small slds-theme_shade slds-m-top_medium slds-m-bottom_medium slds-scrollable_x"><code class="language-json">{"type": "object"} </code></pre>
              <pre class="line-numbers slds-box slds-box_x-small slds-theme_shade slds-m-top_medium slds-m-bottom_medium slds-scrollable_x"><code class="language-json">{"type": "object", "properties": {}}</code></pre>
            </td>

          </tr>
          <tr class="">
            <td data-label="Supported JSON Responses" class="slds-cell-wrap" style="vertical-align:top;" headers="d101459e87 ">A 1st-level property whose type is object, even if that object has no
              properties field</td>

            <td data-label="Examples" class="slds-cell-wrap" style="vertical-align:top;" headers="d101459e90 ">
              <pre class="line-numbers slds-box slds-box_x-small slds-theme_shade slds-m-top_medium slds-m-bottom_medium slds-scrollable_x"><code class="language-json">{
  "type": "object",
  "properties": {
    "prop1": {
      "type": "object"
    }
  }
} </code></pre>
              <pre class="line-numbers slds-box slds-box_x-small slds-theme_shade slds-m-top_medium slds-m-bottom_medium slds-scrollable_x"><code class="language-json">{
  "type": "object",
  "properties": {
    "prop1": {
      "type": "object",
      "properties": {}
    }
  }
}</code></pre>
            </td>

          </tr>
          <tr class="">
            <td data-label="Supported JSON Responses" class="slds-cell-wrap" style="vertical-align:top;" headers="d101459e87 ">A 1st-level property whose type is an array of object, where the object has no
              properties field</td>

            <td data-label="Examples" class="slds-cell-wrap" style="vertical-align:top;" headers="d101459e90 ">
              <pre class="line-numbers slds-box slds-box_x-small slds-theme_shade slds-m-top_medium slds-m-bottom_medium slds-scrollable_x"><code class="language-json">{
  "type": "object",
  "properties": {
    "prop1": {
      "type": "array",
      "items": {
        "type": "object"
      }
    }
  }
}</code></pre>
              <pre class="line-numbers slds-box slds-box_x-small slds-theme_shade slds-m-top_medium slds-m-bottom_medium slds-scrollable_x"><code class="language-json">{
  "type": "object",
  "properties": {
    "prop1": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {}
      }
    }
  }
}</code></pre>
            </td>

          </tr>
        </tbody>
      </table>

## Lightning Types

All agent actions use Lightning types to define the structure of, validate, and display the data in inputs and outputs. The input and output schemas of MCP tools don’t always map to Lightning types, because the data type is defined by the server and the protocol supports a wide range of data types. For example, when a data type contains an operator, such as any/or. Learn more about [standard Lightning types](https://developer.salesforce.com/docs/platform/lightning-types/references/lightning-types/lightning-types-reference.html) and [how Lightning types are used in agent actions](https://developer.salesforce.com/docs/ai/agentforce/guide/lightning-types-standard.html).

When data can’t be resolved to a Lightning type, you can view the input and output schema for the tool on the record page for the MCP server in the Agentforce Registry. But the input or output appears empty for the associated MCP tool action in the asset library and in your agent.

You can still use the MCP tool action with your agent, but the input or output can’t be stored in a variable or used in downstream logic or instructions.

- The action can’t be [chained to another action in sequence](https://developer.salesforce.com/docs/ai/agentforce/guide/ascript-patterns-action-chaining.html) deterministically. However, in reasoning, the agent can choose relevant inputs and outputs.
- The action can’t be [run deterministically in reasoning instructions](https://developer.salesforce.com/docs/ai/agentforce/guide/ascript-patterns-fetch-data.html), because each input and output must be mapped to a variable.
- You can’t use outputs that don’t resolve to Lightning types in [conditional statements](https://developer.salesforce.com/docs/ai/agentforce/guide/ascript-patterns-conditionals.html) or [filters](https://developer.salesforce.com/docs/ai/agentforce/guide/ascript-patterns-filtering.html).

For best results, plan for agent reasoning over deterministic behavior in your agent design and configure simple, natural language subagent instructions.

Here's an example of an MCP tool with an output that doesn't map to a Lightning type.

- Input and output schemas on the MCP server record page:
    
    ![Input and output schemes on MCP server record page](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-ai-generative_ai-264-0-0-production-enus/f8ef6498-d7b2-44e3-9b34-ffd5a850aae9/generative_ai/images/agent_mcp_schemas.png)
- An empty output for the associated MCP tool action in the asset library:
    
    ![An empty output for an MCP tool action in the asset library](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-ai-generative_ai-264-0-0-production-enus/f8ef6498-d7b2-44e3-9b34-ffd5a850aae9/generative_ai/images/agent_mcp_empty_output_library.png)
- An empty output for the associated MCP tool action in an agent:
    
    ![An empty output for an MCP tool action in an agent](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-ai-generative_ai-264-0-0-production-enus/f8ef6498-d7b2-44e3-9b34-ffd5a850aae9/generative_ai/images/agent_mcp_empty_output_agent.png)