This article shows you how to connect your Model Context Protocol (MCP) server hosted on Azure Functions to Microsoft Foundry Agent Service. After completing this guide, your agent can discover and invoke the tools exposed by your MCP server.
This article follows this basic process for configuring the MCP server connection from Foundry Agent Service:
- Create and deploy an MCP server to your function app in Azure.
- Get the MCP server endpoint URL.
- Get the authentication credentials (as required).
- Disable key-based authentication (when not needed).
- Add an MCP server tool connection to an existing agent.
Prerequisites
Before you begin, make sure you have these resources in place:
Review connection options
This table summarizes the currently supported options for authenticating your agent connection to an MCP server in Foundry Agent Service:
| Method |
Description |
Use case |
Additional setup |
Functions supports |
| Key-based (default) |
Agent authenticates by passing a shared function access key in the request header. This method is the default authentication for HTTP endpoints in Functions. |
Use during development or when the MCP server doesn't require Microsoft Entra authentication. |
None |
Yes |
| Microsoft Entra |
Agent authenticates using either its own identity (agent identity) or the shared identity of the Foundry project (project managed identity). |
Use agent identity for production scenarios, but limit shared identity to development. |
Disable key-based authentication and configure built-in server authorization and authentication. |
Project managed (shared) identity |
| OAuth identity passthrough |
Agent prompts users to sign in and authorize access, using the provided token to authenticate. |
Use in production when each user must authenticate with their own identity and user context must be persisted. |
Disable key-based authentication and configure built-in server authorization and authentication. |
Yes |
| Unauthenticated access |
Agent makes unauthenticated calls. |
Use during development or when your MCP server accesses only public information. |
Disable key-based authentication. |
Yes |
To learn more about the MCP server authentication options that the Foundry Agent Service supports, see Set up authentication for MCP tools.
Get the remote MCP server endpoint
Before you can connect the agent to a Functions-hosed MCP server, you must get the endpoint URL for the service. The specific URL format depends on how you created and deployed your MCP server:
| MCP server type |
Endpoint format |
| MCP extension-based server |
https://<FUNCTION_APP_NAME>.azurewebsites.net/runtime/webhooks/mcp |
| Self-hosted MCP server |
https://<FUNCTION_APP_NAME>.azurewebsites.net/mcp (unless you changed the route) |
For more information, see Remote MCP servers.
Get credentials
The credentials that your agent needs to connect to the MCP server depend on the way you plan to secure the connection. Choose the tab that indicates your connection authentication option.
When you use an access key to connect to your MCP server endpoint, you use a shared secret key to make it more difficult for random agents to connect to your server.
Important
While access keys can help prevent unwanted endpoint access by default, consider using Microsoft Entra ID or OAuth identity authentication to provide enhanced security to your MCP server endpoints in production.
The name of the access key you need depends on your MCP server deployment:
| MCP server type |
Key name |
Key type |
| MCP extension-based server |
mcp_extension |
System key |
| Self-hosted MCP server |
default |
Host key |
To get the key from the Azure portal:
- Go to your function app resource in the Azure portal.
- Expand the Functions dropdown in the left menu.
- Select App keys.
- Copy either the
mcp_extension key (under System keys) or the default key (under Host keys), depending on your MCP server type.
For more information, see Work with access keys in Azure Functions.
Both Agent Identity and Project Managed Identity use Microsoft Entra authentication. Currently, Functions only supports Project managed identity, which requires your server to use built-in authentication and authorization.
If your function app doesn't have a user-assigned managed identity, first create one.
Connect the user-assigned managed identity from your function app to your Foundry project:
In the Azure portal, search for Foundry. In Microsoft Foundry, select your Foundry resource from All resources.
In Resource management > Identity > User assigned, select + Add. Select the user-assigned managed identity used by your function app, and then select Add.
Select the newly added identity and copy the Client ID value.
Add the user-assigned managed identity as an allowed client application in your function app's Entra app registration:
Go to your function app resource in the Azure portal.
Select Settings > Authentication from the left menu.
Select the Edit icon for your registered Entra identity provider.
In your provider, set Client application requirement to Allow requests from specific client applications and select the edit button next to Allowed client applications.
Add the client ID of your user-assigned managed identity, and select OK and then Save.
Get the Application ID URI from your function app's Entra app registration, which you need to complete the Entra authentication registration in your agent:
Back in the Authentication page for your app, select the name of the registered Entra identity provider. This selection takes you to the Entra app resource page.
In the left menu, select Manage > Expose an API.
Copy the Application ID URI at the top of the page. This ID value looks like api://00001111-aaaa-2222-bbbb-3333cccc4444.
OAuth identity passthrough prompts users to sign in and authorize access to your MCP server. For a Functions-hosted MCP server with built-in authentication, use custom OAuth with a Microsoft Entra app registration.
To get the required credentials from the Azure portal:
Go to your function app resource in the Azure portal.
Select Settings > Authentication from the left menu.
Select the name of the Entra app next to Microsoft. This selection takes you to the Entra app resource.
From Essentials in the Overview page, copy the values from these fields:
- Application (client) ID
- Directory (tenant) ID
- Application ID URI
Use the tenant ID to construct these required OAuth URLs:
| URL type |
Format |
| Auth URL |
https://login.microsoftonline.com/<TENANT_ID>/oauth2/v2.0/authorize |
| Token URL |
https://login.microsoftonline.com/<TENANT_ID>/oauth2/v2.0/token |
| Refresh URL |
https://login.microsoftonline.com/<TENANT_ID>/oauth2/v2.0/token |
Replace <TENANT_ID> with your actual tenant ID value.
Select Manage > Expose an API and copy the existing scope.
After you configure OAuth identity passthrough in the Foundry portal, you receive a redirect URL. You must return to your Entra app registration to add this redirect URL to the Microsoft Entra app registration.
Because unauthenticated access requires no shared secrets or authentication, you can skip to the next section.
Important
This option allows any client or agent to access your MCP server endpoint. Use it only for tools that return read-only public information or during private development.
Disable key-based authentication
When you choose to use a different authentication method than the default key-based authentication, you don't need Functions to enforce key-based access to your MCP endpoints. You can disable key-based access requirement by changing the access setting from system (key-based) to anonymous (unauthenticated). How you make this change depends on the type of MCP server you're hosting:
When you use the default key-based authentication, no changes are required.
To disable host-based authentication in your MCP server, add a setting named AzureFunctionsJobHost__extensions__mcp__system__webhookAuthorizationLevel with a value of Anonymous to your application settings. You can add this setting in the portal or use the following Azure CLI command:
az functionapp config appsettings set --name <APP_NAME> --resource-group <RESOURCE_GROUP> \
--settings "AzureFunctionsJobHost__extensions__mcp__system__webhookAuthorizationLevel=Anonymous"
In this example, replace <APP_NAME> and <RESOURCE_GROUP> with the name of your function app and resource group.
Tip
This setting is equivalent to setting system.webhookAuthorizationLevel to Anonymous in the MCP Extension section of the host.json file. However, that method requires you to republish your server project.
To disable host-based authentication in your MCP server, add a setting named AzureFunctionsJobHost__extensions__mcp__system__webhookAuthorizationLevel with a value of Anonymous to your application settings. You can add this setting in the portal or use the following Azure CLI command:
az functionapp config appsettings set --name <APP_NAME> --resource-group <RESOURCE_GROUP> \
--settings "AzureFunctionsJobHost__extensions__mcp__system__webhookAuthorizationLevel=Anonymous"
In this example, replace <APP_NAME> and <RESOURCE_GROUP> with the name of your function app and resource group.
Tip
This setting is equivalent to setting system.webhookAuthorizationLevel to Anonymous in the MCP Extension section of the host.json file. However, that method requires you to republish your server project.
To disable host-based authentication in your MCP server, add a setting named AzureFunctionsJobHost__extensions__mcp__system__webhookAuthorizationLevel with a value of Anonymous to your application settings. You can add this setting in the portal or use the following Azure CLI command:
az functionapp config appsettings set --name <APP_NAME> --resource-group <RESOURCE_GROUP> \
--settings "AzureFunctionsJobHost__extensions__mcp__system__webhookAuthorizationLevel=Anonymous"
In this example, replace <APP_NAME> and <RESOURCE_GROUP> with the name of your function app and resource group.
Tip
This setting is equivalent to setting system.webhookAuthorizationLevel to Anonymous in the MCP Extension section of the host.json file. However, that method requires you to republish your server project.
Skip this section when using key-based authentication.
To disable host-based authentication in your MCP server, add a setting named AzureFunctionsJobHost__customHandler__http__DefaultAuthorizationLevel with a value of anonymous to your application settings. You can add this setting in the portal or use the following Azure CLI command:
az functionapp config appsettings set --name <APP_NAME> --resource-group <RESOURCE_GROUP> \
--settings "AzureFunctionsJobHost__customHandler__http__DefaultAuthorizationLevel=anonymous"
In this example, replace <APP_NAME> and <RESOURCE_GROUP> with the name of your function app and resource group.
Tip
This setting is equivalent to setting http.DefaultAuthorizationLevel to anonymous in the custom handler section of the host.json file. That approach requires you to republish your server project.
To disable host-based authentication in your MCP server, add a setting named AzureFunctionsJobHost__customHandler__http__DefaultAuthorizationLevel with a value of anonymous to your application settings. You can add this setting in the portal or use the following Azure CLI command:
az functionapp config appsettings set --name <APP_NAME> --resource-group <RESOURCE_GROUP> \
--settings "AzureFunctionsJobHost__customHandler__http__DefaultAuthorizationLevel=anonymous"
In this example, replace <APP_NAME> and <RESOURCE_GROUP> with the name of your function app and resource group.
Tip
This setting is equivalent to setting http.DefaultAuthorizationLevel to anonymous in the custom handler section of the host.json file. That approach requires you to republish your server project.
To disable host-based authentication in your MCP server, add a setting named AzureFunctionsJobHost__customHandler__http__DefaultAuthorizationLevel with a value of anonymous to your application settings. You can add this setting in the portal or use the following Azure CLI command:
az functionapp config appsettings set --name <APP_NAME> --resource-group <RESOURCE_GROUP> \
--settings "AzureFunctionsJobHost__customHandler__http__DefaultAuthorizationLevel=anonymous"
In this example, replace <APP_NAME> and <RESOURCE_GROUP> with the name of your function app and resource group.
Tip
This setting is equivalent to setting http.DefaultAuthorizationLevel to anonymous in the custom handler section of the host.json file. That approach requires you to republish your server project.
Add your MCP server
The process for creating the agent connection to the MCP server depends on your specific endpoint authentication options.
When you use key-based authentication, the agent authenticates by passing a function access key in the request header to your MCP server.
To connect to your MCP server endpoint:
Go to the Foundry portal (new Foundry).
Select the Build tab at the top of the page and select an agent to connect to your MCP server.
In the Playground tab, expand the Tools dropdown and select Add.
In the Custom tab in Select a tool, select Model Context Protocol (MCP) > Create.
In Add Model Content Protocol tool, provide information from this table to configure an access key-based connection:
| Field |
Description |
Example |
| Name |
A unique identifier for your MCP server. Use your function app name as the default. |
contoso-mcp-tools |
| Remote MCP Server endpoint |
The URL endpoint for your MCP server. |
https://contoso-mcp-tools.azurewebsites.net/runtime/webhooks/mcp |
| Authentication |
The authentication method to use. |
Key-based |
| Credential |
The key-value pair to authenticate with your function app. |
x-functions-key: aaaaaaaa-0b0b-1c1c-2d2d-333333333333 |
Select Connect to create a connection to your MCP server endpoint. You see your server name listed under Tools.
Select Save to save the MCP tool configuration in your agent.
When you use Microsoft Entra authentication, the agent authenticates by using a managed identity to connect to your MCP server.
To connect to your MCP server endpoint:
Go to the Foundry portal (new Foundry).
Select the Build tab at the top of the page and select an agent to connect to your MCP server.
In the Playground tab, expand the Tools dropdown and select Add.
In the Custom tab in Select a tool, select Model Context Protocol (MCP) > Create.
In Add Model Content Protocol tool, enter the information from this table to configure a Microsoft Entra-based connection:
| Field |
Description |
Example |
| Name |
A unique identifier for your MCP server. You can use your function app name. |
contoso-mcp-tools |
| Remote MCP Server endpoint |
The URL endpoint for your MCP server. |
https://contoso-mcp-tools.azurewebsites.net/runtime/webhooks/mcp |
| Authentication |
The authentication method to use. |
Microsoft Entra |
| Type |
The identity type the agent uses to authenticate. |
Project Managed Identity |
| Audience |
The Application ID URI of your function app's Entra registration. This value tells the identity provider which app the token is intended for. |
api://00001111-aaaa-2222-bbbb-3333cccc4444 |
Select Connect to create a connection to your MCP server endpoint. You see your server name listed under Tools.
Select Save to save the MCP tool configuration in your agent.
When you use OAuth identity passthrough, the agent prompts the user to sign in and then uses the returned access token when connecting to the server.
Go to the Foundry portal (new Foundry).
Select the Build tab at the top of the page and select an agent to connect to your MCP server.
In the Playground tab, expand the Tools dropdown and select Add.
In the Custom tab in Select a tool, select Model Context Protocol (MCP) > Create.
In Add Model Content Protocol tool, enter the information from this table to configure OAuth Identity Passthrough connection:
| Field |
Description |
Example |
| Name |
A unique identifier for your MCP server. You can use your function app name. |
contoso-mcp-tools |
| Remote MCP Server endpoint |
The URL endpoint for your MCP server. |
https://contoso-mcp-tools.azurewebsites.net/runtime/webhooks/mcp |
| Authentication |
The authentication method to use. |
OAuth Identity Passthrough |
| Client ID |
The client ID of your function app Entra registration |
00001111-aaaa-2222-bbbb-3333cccc4444 |
| Token URL |
The endpoint your server app calls to exchange an authorization code or credential for an access token. |
https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/oauth2/v2.0/token |
| Auth URL |
The endpoint where users are redirected to authenticate and grant authorization to your server app. |
https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/oauth2/v2.0/authorize |
| Refresh URL |
The endpoint used to obtain a new access token when the current one expires. |
https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/oauth2/v2.0/token |
| Scopes |
The specific permissions or resource access levels your server app requests from the authorization server |
api://00001111-aaaa-2222-bbbb-3333cccc4444 |
Note
A Client secret value isn't needed, so leave this field blank.
Select Connect to create a connection to your MCP server endpoint.
After you create your credential provider, you receive a Redirect URL. Before you Close this window, make sure to copy the URL value. You must add this redirect URL to your Entra app registration.
Return to your Entra app registration and under Manage > Authentication select + Add redirect URI. Select Web, paste the copied Redirect URI value, and select Configure.
Go back to the agent window, select Close > Save to save the MCP tool configuration in your agent.
Use unauthenticated access only when your MCP server doesn't require authentication and accesses only public information.
To connect to your MCP server endpoint:
Go to the Foundry portal (new Foundry).
Select the Build tab at the top of the page and select an agent to connect to your MCP server.
In the Playground tab, expand the Tools dropdown and select Add.
In the Custom tab in Select a tool, select Model Context Protocol (MCP) > Create.
In Add Model Content Protocol tool, provide information from this table to configure an unauthenticated connection:
| Field |
Description |
Example |
| Name |
A unique identifier for your MCP server. You can use your function app name. |
contoso-mcp-tools |
| Remote MCP Server endpoint |
The URL endpoint for your MCP server. |
https://contoso-mcp-tools.azurewebsites.net/runtime/webhooks/mcp |
| Authentication |
The authentication method to use. |
Unauthenticated |
Select Connect to create an unauthenticated connection to your MCP server endpoint. You should now see your server name listed under Tools.
Select Save to save the MCP tool configuration in your agent.
After connecting your MCP server to your agent, verify that the tools work correctly.
- In the Agent Builder, find the chat window under Playground.
- Enter a prompt that triggers one of your MCP tools. For example, if your MCP server has a greeting tool, try:
Use the greeting tool to say hello.
- If you're using OAuth identity passthrough, select Open Consent and sign in with your Entra account.
- When the agent requests to invoke an MCP tool, review the tool name and arguments, and select Approve to allow the call.
- Verify the tool returns the expected result.
Your agent can now use the tools exposed by your MCP server hosted on Azure Functions.
Related articles
These additional articles can help you build your agent and function app capabilities: