Blog Post

Azure Integration Services Blog
5 MIN READ

Bring your own APIs and MCP servers: custom connectors in Connector Namespace

WSilveira's avatar
WSilveira
Icon for Microsoft rankMicrosoft
Nov 17, 2026

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 connectorMCP server custom connector
You provideAn OpenAPI definition of your REST APIThe URL of a remote MCP server
Tools come fromThe namespace, generated from the operations you exposeYour MCP server, passed through as-is
Typical useInternal APIs that don't speak MCPYour 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, and tools/call to 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.

Contoso's agent reaches both systems through MCP endpoints in one connector namespace. Each custom connector's connection holds the backend API key.

Creating tools from your REST API

Step 1: Create the custom connector

  1. Open your namespace at connectors.azure.com, select Custom connectors, then + Create.
  2. Name it ContosoOrders and choose OpenAPI.
  3. Upload the Orders API definition.
  4. 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.
ContosoOrders creation review page, showing endpoint, configuration, and actions.

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.

New connection for contoso-orders showing the API key field

 

Step 3: Create the MCP connector

  1. Select MCP Connectors, then + Create. Under Choose a connector, pick ContosoOrders, then select the connection you just made on the Authentication step. Name it OrdersMCP.
  2. On the Tools step, select the operations to expose as tools, such as GetOrder and ListOrdersByCustomer. Leave out anything the agent shouldn't call, such as CancelOrder.
OrdersMCP Tools tab with GetOrder and ListOrdersByCustomer selected and CancelOrder cleared

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.

OrdersMCP with the two tools selected showing in the MCP playground.

 

Path B: your MCP server, through the namespace

Step 1: Connect the endpoint

  1. Select MCP Connectors, then + Create. Under Connect an MCP server, find Connect an existing MCP endpoint and select Configure endpoint.
  2. Enter the server URL, for example https://mcp.fabrikam.example/mcp, and name the MCP connector FabrikamInventoryMCP.
  3. 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.

FabrikamInventoryMCP in playground

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

Updated Nov 14, 2026
Version 1.0
No CommentsBe the first to comment