MCP for Agentforce Metadata in Managed Packages

Bring the capabilities of your externally hosted Model Context Protocol (MCP) servers to Agentforce by configuring, securely packaging, and distributing your MCP server registration. Learn how to set up your Salesforce DX project and create the MCP server registration.

See MCP for Agentforce in Salesforce Help for more information on MCP servers for Agentforce.

MCP for Agentforce Metadata Components

The underlying MCP server definition comprises four packageable metadata types.

Feature Name	Metadata Name	Available In	More Information
External Credential	ExternalCredential	Managed 2GP and Managed 1GP	Contains the named principal and authentication parameters required for the MCP connection.
External Service Registration	ExternalServiceRegistration	Managed 2GP and Managed 1GP	Defines the registration provider and schema type specifically as ModelContextProtocol.
Named Credential	NamedCredential	Managed 2GP and Managed 1GP	Manages the callout endpoint details for your MCP server.
Permission Set	PermissionSet	Managed 2GP and Managed 1GP	Grants your users access to the necessary External Credential Principal and Read access to the User External Credential object.

When you create an MCP server registration through Agentforce Registry in Setup, the components follow the correct naming conventions and the dependencies between them are established.

These components aren’t packageable at this time.

MCP tool actions, which are agent actions that reference server tools.
Agentforce Gateway policies, which set governance rules, define usage limits, and control access to MCP tools and other APIs.

Note

Set Up Your Salesforce DX Project and Scratch Org

Depending on your use case, you can package the MCP server registration either as a component of an Agentforce extension package or as a standalone managed package.

To work with Agentforce as an MCP client, configure your Salesforce DX project and provision a scratch org with the Chatbot and Einstein1AIPlatform features enabled.

Update your project configuration file (sfdx-project.json) to use API version 66.0 or greater and set your namespace.

Update your scratch org definition file (project-scratch-def.json) to include the required Chatbot and Einstein1AIPlatform features.

Scratch orgs are the primary means by which partners develop MCP server registration metadata.

Note

1{
2  "orgName": "Appy Industries",
3  "edition": "Partner Developer",
4  "features": ["Chatbot", "Einstein1AIPlatform"],
5  "settings": {
6    "botSettings": {
7      "enableBots": true
8    }
9  }
10}

Create and Retrieve the MCP Server Registration

Create an MCP server registration by following the instructions in Register a Third-Party MCP Server in Agentforce Registry in Salesforce Help.

To configure an MCP server using an authentication type other than OAuth 2.0 Client Credential Flow, enter your MCP server endpoint URL and select No Auth for the Authentication Method. If your MCP server supports unauthenticated tool/list requests, you can configure the required authentication method later. If your MCP server requires authenticated tool/list requests, follow the instructions in the Example Metadata for Establishing an MCP Server Registration section.
Note

After you register the MCP server, retrieve the MCP server metadata by running the project retrieve start Salesforce CLI command.

1sf project retrieve start \
2  --metadata "ExternalCredential:{MCP_SERVER_NAME}" \
3  --metadata "ExternalServiceRegistration:{MCP_SERVER_NAME}" \
4  --metadata "NamedCredential:{MCP_SERVER_NAME}" \
5  --metadata "PermissionSet:{MCP_SERVER_NAME}_Perm_Set" \
6  --target-org {ORG_ALIAS}

Deploy and Activate the MCP Server

Deploy the MCP server metadata and assign the MCP permission set by using Salesforce CLI commands. Then, activate the MCP server in Setup.

Deploy the MCP server metadata by running the project deploy start CLI command with the metadata that you retrieved.

1sf project deploy start \
2  --metadata "ExternalCredential:{MCP_SERVER_NAME}" \
3  --metadata "ExternalServiceRegistration:{MCP_SERVER_NAME}" \
4  --metadata "NamedCredential:{MCP_SERVER_NAME}" \
5  --metadata "PermissionSet:{MCP_SERVER_NAME}_Perm_Set" \
6  --target-org {ORG_ALIAS}

Assign the MCP server permission set by running the org assign permset CLI command.

1sf org assign permset --name {MCP_SERVER_NAME}_Perm_Set --target-org {ORG_ALIAS}

Activate the MCP server through Setup.

These steps are specific to the OAuth 2.0 Client Credentials Flow authorization type. Depending on your MCP server authentication method, your specific configuration can differ.
Note
1. From Setup, in the Quick Find box, enter Agentforce Registry, and then select MCP Servers.
2. Click the name of the MCP server that you deployed. The Connection Status is disconnected.
3. Under Authentication Details, click the Named Credential listed for your MCP server.
4. On the Named Credential page, click the External Credential.
5. On the External Credential page, scroll down to the Principals section, which displays one principal with a parameter name of MCPAuthentication. Click the Actions drop-down menu, and then select Edit.
6. Enter the Client ID and Client Secret. Then, click Save.
7. Navigate back to the MCP Servers page in Setup. Select your MCP server and confirm that the Connection Status is now Active.
8. Click the Tools tab, and then click Manage Tools. Select the tools to activate in the org, and then save your changes.
9. From Setup, in the Quick Find box, enter Agentforce Assets, and then select Agentforce Assets.
10. Click the Actions tab to view the newly created MCP tool actions, which are indicated by an orange icon ().

Example Metadata for Establishing an MCP Server Registration

As an alternative way to establish an MCP server registration in an org, you can manually generate metadata to include in your Salesforce DX project. We recommend manually generating metadata if you’re configuring an authorization type other than the OAuth 2.0 Client Credentials Flow authorization type and your MCP server requires authenticated tool/list requests.

In the metadata examples, replace these placeholder values with the values for your package or MCP server.

When you replace the placeholder values, make sure to also remove the brackets. For example, replace {NAMESPACE} with astro__.

Note

NAMESPACE: Package namespace, if applicable. Include double underscores after your namespace. For example: astro__
MCP_SERVER_NAME: Name of your MCP service, which contains only alphanumeric characters. Make sure to enter the MCP service name in both the file names and within the files.
MCP_SERVER_URL: Endpoint for your MCP server.

externalCredentials/{MCP_SERVER_NAME}.externalCredential-meta.xml

1<?xml version="1.0" encoding="UTF-8"?>
2<ExternalCredential xmlns="http://soap.sforce.com/2006/04/metadata">
3    <authenticationProtocol>Custom</authenticationProtocol>
4    <externalCredentialParameters>
5        <parameterGroup>DefaultGroup</parameterGroup>
6        <parameterName>Custom</parameterName>
7        <parameterType>AuthProtocolVariant</parameterType>
8        <parameterValue>NoAuthentication</parameterValue>
9    </externalCredentialParameters>
10    <externalCredentialParameters>
11        <parameterGroup>MCPAuthentication</parameterGroup>
12        <parameterName>MCPAuthentication</parameterName>
13        <parameterType>NamedPrincipal</parameterType>
14        <sequenceNumber>1</sequenceNumber>
15    </externalCredentialParameters>
16    <label>{MCP_SERVER_NAME}</label>
17</ExternalCredential>

externalServiceRegistrations/{MCP_SERVER_NAME}.externalServiceRegistration-meta.xml

1<?xml version="1.0" encoding="UTF-8"?>
2<ExternalServiceRegistration xmlns="http://soap.sforce.com/2006/04/metadata">
3    <label>{MCP_SERVER_NAME}</label>
4    <namedCredential>{NAMESPACE}{MCP_SERVER_NAME}</namedCredential>
5    <namedCredentialReference>{MCP_SERVER_NAME}</namedCredentialReference>
6    <registrationProviderType>ModelContextProtocol</registrationProviderType>
7    <schema>{&quot;serverDescriptor&quot;:{&quot;protocolVersion&quot;:&quot;2025-06-18&quot;,&quot;serverInfo&quot;:{&quot;name&quot;:&quot;{MCP_SERVER_NAME}&quot;,&quot;version&quot;:&quot;1.0.0&quot;}},&quot;tools&quot;:[],&quot;resources&quot;:[]}</schema>
8    <schemaType>ModelContextProtocol</schemaType>
9    <serviceBinding>{&quot;protocolVersion&quot;:&quot;2025-06-18&quot;,&quot;serverInfo&quot;:{&quot;name&quot;:&quot;{MCP_SERVER_NAME}&quot;,&quot;version&quot;:&quot;1.0.0&quot;},&quot;instructions&quot;:null}</serviceBinding>
10    <status>Incomplete</status>
11    <systemVersion>8</systemVersion>
12</ExternalServiceRegistration>

namedCredentials/{MCP_SERVER_NAME}.namedCredential-meta.xml

1<?xml version="1.0" encoding="UTF-8"?>
2<NamedCredential xmlns="http://soap.sforce.com/2006/04/metadata">
3    <allowMergeFieldsInBody>true</allowMergeFieldsInBody>
4    <allowMergeFieldsInHeader>true</allowMergeFieldsInHeader>
5    <calloutStatus>Enabled</calloutStatus>
6    <generateAuthorizationHeader>true</generateAuthorizationHeader>
7    <label>{MCP_SERVER_NAME}</label>
8    <namedCredentialParameters>
9        <parameterName>Url</parameterName>
10        <parameterType>Url</parameterType>
11        <parameterValue>https://{MCP_SERVER_URL}</parameterValue>
12    </namedCredentialParameters>
13    <namedCredentialParameters>
14        <externalCredential>{NAMESPACE}{MCP_SERVER_NAME}</externalCredential>
15        <parameterName>ExternalCredential</parameterName>
16        <parameterType>Authentication</parameterType>
17    </namedCredentialParameters>
18    <namedCredentialType>SecuredEndpoint</namedCredentialType>
19</NamedCredential>

permissionsets/{MCP_SERVER_NAME}_Perm_Set.permissionset-meta.xml

1<?xml version="1.0" encoding="UTF-8"?>
2<PermissionSet xmlns="http://soap.sforce.com/2006/04/metadata">
3    <description>Perm set for MCP Server &apos;MCP_SERVER_NAME&apos;</description>
4    <externalCredentialPrincipalAccesses>
5        <enabled>true</enabled>
6        <externalCredentialPrincipal>{NAMESPACE}{MCP_SERVER_NAME}-MCPAuthentication</externalCredentialPrincipal>
7    </externalCredentialPrincipalAccesses>
8    <hasActivationRequired>false</hasActivationRequired>
9    <label>MCP_SERVER_NAME - Permission Set</label>
10    <objectPermissions>
11        <allowCreate>false</allowCreate>
12        <allowDelete>false</allowDelete>
13        <allowEdit>false</allowEdit>
14        <allowRead>true</allowRead>
15        <modifyAllRecords>false</modifyAllRecords>
16        <object>UserExternalCredential</object>
17        <viewAllFields>false</viewAllFields>
18        <viewAllRecords>false</viewAllRecords>
19    </objectPermissions>
20</PermissionSet>