Your agent already talks to Salesforce and SharePoint through Connector Namespace. Then it needs your order system. Or a partner sends you the URL of their MCP server. Neither one is in the catalog, and you're back to keeping secrets in app settings and writing your own access checks. Custom connectors close that gap.
What is a custom connector
A custom connector describes an API or MCP server that isn't in the managed catalog, so your namespace can call it like any other connector. You register it once in the namespace, next to the 1,400+ managed connectors, then build connections and MCP connectors from it.
There are two kinds:
| OpenAPI custom connector | MCP server custom connector | |
|---|---|---|
| You provide | An OpenAPI definition of your REST API | The URL of a remote MCP server |
| Tools come from | The namespace, generated from the operations you expose | Your MCP server, passed through as-is |
| Typical use | Internal APIs that don't speak MCP | Your own or a partner's MCP server |
Both kinds use the same building blocks as managed connectors. A connection holds the backend credential. An MCP connector publishes the MCP endpoint your agents call.
Why it matters
Agents rarely work only with catalog systems. The order API, the pricing service, the partner's inventory server: that's where the work happens. Without custom connectors, each one needs its own credential store, its own caller checks, and its own MCP plumbing.
With custom connectors, your systems get the same treatment as Salesforce or ServiceNow:
- Secrets stay in the namespace. The backend API key or OAuth token lives in the connection. Your agent never sees it.
- One access model. Callers present a Microsoft Entra ID token, and access policies on the MCP connector decide who gets in.
- One endpoint shape. Your agent calls your API, your partner's server, and every catalog connector through MCP endpoints from the same namespace.
Targets: MCP custom connectors
This post covers MCP connectors built on custom connectors, using a shared connection: everyone you admit uses the same backend credential, so scope it to what the agent needs. The two kinds behave differently once they're behind an MCP connector:
- OpenAPI custom connector: generated tools. The namespace turns each operation you expose into a tool, so clear operation IDs and summaries in your definition make better tools.
- MCP server custom connector: passthrough. The namespace forwards
initialize,tools/list, andtools/callto your server. Your server owns its tool names, schemas, and results. The namespace decides who can call it and which credential it sends.
Two related topics are covered elsewhere. Hosted MCP servers, where the namespace runs the server for you, are in Hosted MCP servers in Connector Namespace. Per-user authentication works with custom connectors that use OAuth, and the OBO deep dive explains it.
Prerequisites
- A connector namespace, plus Owner or Contributor on it. See Create a connector namespace.
- For an OpenAPI custom connector: an OpenAPI 2 or 3 definition of your API, and an HTTPS endpoint the namespace can reach.
- For an MCP server custom connector: a remote MCP server that accepts streamable HTTP over HTTPS. The namespace calls it with HTTP POST. It doesn't run local stdio servers.
- The backend credential for each system, such as an API key.
- The object IDs of the users, groups, or apps that will call the MCP connectors.
Walkthrough: Contoso orders
Contoso's customer service agent answers "where's my order?" questions. It needs two systems that aren't in the catalog:
- Contoso Orders API, an internal REST API with an OpenAPI definition, protected by an API key.
- Fabrikam inventory, an MCP server run by Contoso's logistics partner, also protected by an API key.
You'll build one MCP connector for each, then point the agent at both endpoints.
Creating tools from your REST API
Step 1: Create the custom connector
- Open your namespace at connectors.azure.com, select Custom connectors, then + Create.
- Name it
ContosoOrdersand choose OpenAPI. - Upload the Orders API definition.
- Under authentication, choose API key and set the header the API expects, such as
X-Contoso-Key. You don't enter the key here. It goes in the connection.
Step 2: Create the connection
Select Connections, then + Create, and pick ContosoOrders. Paste the Orders API key and save. The key now lives in the namespace.
Step 3: Create the MCP connector
- Select MCP Connectors, then + Create. Under Choose a connector, pick
ContosoOrders, then select the connection you just made on the Authentication step. Name itOrdersMCP. - On the Tools step, select the operations to expose as tools, such as
GetOrderandListOrdersByCustomer. Leave out anything the agent shouldn't call, such asCancelOrder.
Step 4: Test in the playground
On the MCP connector's Settings tab, turn on API key under Authentication, then select Playground. Run Initialize and List tools, then call GetOrder with a real order number. When you're done testing, turn API key authentication off again: API keys skip access policies.
Path B: your MCP server, through the namespace
Step 1: Connect the endpoint
- Select MCP Connectors, then + Create. Under Connect an MCP server, find Connect an existing MCP endpoint and select Configure endpoint.
- Enter the server URL, for example
https://mcp.fabrikam.example/mcp, and name the MCP connectorFabrikamInventoryMCP. - On the Authentication step, choose API key, set the header Fabrikam expects, and enter the key Fabrikam gave you.
You don't describe each tool. Behind the scenes, the wizard registers Fabrikam's server as an MCP server custom connector (fabrikam-inventory in Figure 1) with one forwarding operation, and Fabrikam's server lists its own tools.
Create MCP Connector with Connect an existing MCP endpoint, the Fabrikam server URL, and API key authentication
Step 2: Review the tools
Finish the Tools step and create the MCP connector. There's nothing to pick: the agent gets every tool Fabrikam's server lists, so limit tools on the server side.
Step 3: Test in the playground
Open the playground as in path A and run List tools. You see Fabrikam's tools, such as check_stock, not anything the namespace generated.
Feedback
Tell me which API or MCP server you bring in first, and where it fights you. Run both paths against a system you own, then file issues and requests at GitHub Issues. I read every one, and they shape what we build next.
Learn more
- Portal: connectors.azure.com
- Documentation, including limits and protocol details: [Link to custom connector documentation]
- GA announcement: aka.ms/connector-namespace/ga/blog
- OBO deep dive: aka.ms/connector-namespace/obo/blog