Skip to main content

MCP connector

For Studio users with the URL of a Model Context Protocol (MCP) server that speaks streamable HTTP. Agents call the server's tools directly, as their own tools; Studio signs in to the server for them, so the server's credentials never reach the agent's code.

Before you start: the URL must be the http or https endpoint that answers (https for client credentials and AWS IAM), on a public host or, on a private deployment, inside the internal service ranges an administrator approved (Data connectors). Studio supports streamable HTTP only and does not follow redirects.

Create a connector​

  1. Open Data Connectors, click Create Connector, choose MCP Server and fill Connector Name, Description and a one-sentence Connector Guide (step 6 expands it).
  2. In Connection Configuration ("The MCP server endpoint (streamable HTTP). Agents call its tools directly; its credentials stay in AWS Secrets Manager and never reach the sandbox."), enter the MCP Server URL, for example https://mcp.example.com/mcp.
  3. In Authentication Configuration, choose the Sign-in method the server expects and fill its fields (Sign-in methods). When each person signs in with their own account, Test Connection finds the sign-in details and the tools are listed after you connect your own account.
  1. Click Test Connection. Studio signs in, opens a session and lists the server's tools; the result reads Passed. "Connected to server; n tools found." or Failed. with a sentence that says what went wrong (Test Connection results).
  2. Under Tools, choose which tools agents may use and which ask before running (Choose the tools agents may use).
  3. Click Discover Tools & Enrich Guide. Studio streams a guide naming each tool and when to use it. Edit it, then click Accept & Use This Guide (or Discard).
  1. Click Create Connector (v1), enabled when name, description, guide and URL are set, the chosen sign-in method is complete and, once a test has passed, a discovered guide is accepted.
  2. Open the agent, choose Configure, and add the connector (Agents: configure and activate).

Sign-in methods​

Sign-in methodUse it whenWhat you fill in
No authenticationThe server needs no credentialsNothing
Custom headersThe server takes a key or token in a request headerRows of Credential key, an optional header name and Value, up to 12 with Add credential; tick Each person adds their own key to have each person enter their own values (personal keys)
Query parametersThe server takes a key in the URLRows of Query parameter name and Value
Sign in with client credentialsThe server accepts OAuth 2.0 access tokens from your identity provider, for example Microsoft Entra IDToken URL, Scope, Audience (optional), Client authentication, Client ID, Client secret
AWS IAMThe server takes AWS Signature Version 4, for example an Amazon Bedrock AgentCore Gateway with the AWS IAM authoriserRegion, Signing service, and Use this Studio's role or Assume a role with a Role ARN
Sign in with OAuth (each person)The server signs people in with OAuth, including providers that need a sign-in app registered with themEach person connects their own account (Each person signs in)
Sign in with Microsoft (each person)The server, for example an Amazon Bedrock AgentCore Gateway, must receive each person's own Microsoft Entra ID tokenDirectory (tenant) ID, Application (client) ID, Client secret, Scope; each person connects their own Microsoft account (on behalf of each person)

Sign in with client credentials​

Studio gets a token from your identity provider with the client ID and secret, keeps it until shortly before it expires, and sends it to the server as Authorization: Bearer. A new token is fetched when the old one expires or the server rejects it, with no action from you.

  • Token URL: your provider's token endpoint, for example https://login.microsoftonline.com/<tenant>/oauth2/v2.0/token. It must be https.
  • Scope: for Entra ID, the API's application ID URI followed by /.default, for example api://<app-id-uri>/.default.
  • Audience (optional): only if your provider asks for one.
  • Client authentication: Send in the request body (the default) or Send as HTTP Basic, whichever your provider expects.
  • Client ID and Client secret: stored in AWS Secrets Manager. On Update both start blank; blank keeps the stored value.

Amazon Bedrock AgentCore Gateway with Entra ID tokens. On the gateway's JSON Web Token (JWT) authoriser, set the allowed audiences (allowedAudience) to the value the token carries in aud, and leave the allowed clients (allowedClients) empty. Allowed clients checks a client_id claim, and Entra ID access tokens name the calling app in azp (version 2.0) or appid (version 1.0) instead, so the gateway refuses a valid token with 403. When the API's app registration issues version 2.0 access tokens (the token's ver claim reads 2.0), use the discovery URL https://login.microsoftonline.com/<tenant>/v2.0/.well-known/openid-configuration; aud is then the API's Application (client) ID, not its api:// URI. These are settings on the gateway: leave Audience (optional) in Studio blank for Entra ID.

AWS IAM​

Studio signs each request with AWS Signature Version 4; no secret is pasted.

  • Region: read from an AgentCore Gateway URL (<id>.gateway.bedrock-agentcore.<region>.amazonaws.com) when you leave it blank; for any other host, enter it.
  • Signing service: leave blank for bedrock-agentcore.
  • Use this Studio's role: Studio signs with its own role. Allow that role to invoke your gateway.
  • Assume a role: enter the Role ARN of a role in your account. Studio assumes it with an External ID unique to this connector.

Show Role setup (also on the connector's page) gives what to paste into AWS, each with Copy:

ModeRole setup shows
Use this Studio's roleThis Studio's role, the Signing service, the Region and an Example resource policy for the gateway that lets this Studio's role invoke it
Assume a roleExternal ID (unique to this connector; required by the trust policy), the Signing service, the Region, the Trust policy (the role's trust relationship) and an Example permission policy for the role that allows invoking the gateway

The External ID is created by Studio and is read-only in the form. Add the trust policy to the role, give the role permission to invoke the gateway, then test.

Test Connection results​

Test Connection in the form and Test connection on the connector's page run the same check: sign in, open a session and list the tools, within 20 seconds. A failure shows one plain sentence, and a hint where one helps:

What happenedWhat you see
The server refused the credentials (401)"The server rejected the credentials (401). Check the client ID and secret, the scope, or the header values."
The server refused this identity (403)"The server accepted the credentials but refused access (403). Ask the server's owner to allow this identity."
The token endpoint refused the client"The token endpoint rejected the client ID or secret (error)."
The token endpoint returned no token"The token endpoint did not return an access token (HTTP status)."
Studio could not assume the role"Studio could not assume the role role ARN (403). Check that its trust policy allows this Studio and requires the External ID shown in Role setup."
The server's certificate is not trusted"The certificate for host is not issued by a trusted authority. If it comes from your own CA, an administrator can add it under Trusted certificate authorities on the deployment's Overview in Organisations."
The host cannot be reached"Could not reach host. Check the address, and that the server can be reached from this Studio's network."
No answer in time"The server did not answer within n seconds."
The server redirected"The server answered with a redirect. Studio does not follow redirects; enter the final address."
The address is not an MCP endpoint"The server answered but is not an MCP server at this address (HTTP status). Check the path, for example /mcp."
The server failed"The server failed (HTTP status). Try again later."
A shared copy has no credential here yet"This connector needs a credential before agents can use it. Open it in Data Connectors and add one."
You have not connected your account"Connect your account to use this tool."
Your organisation's policy blocks the connector"Blocked by your organisation's policy." and the reason (Connector policy, credentials and activity)

A 403 from an AgentCore Gateway that takes Entra ID tokens can mean the gateway checks allowed clients; set its allowed audiences instead (Sign in with client credentials).

An address refused by the network rules names the host, the address and the reason (Data connectors).

Choose the tools agents may use​

After a passing test, Tools lists every tool the server offers with two switches:

ColumnMeaning
Agents may useOn: agents see the tool and can call it. Off: agents never see it, and a call to it is refused.
Ask before runningOn: each call waits for a person to allow it. Off: the tool runs straight away.

"Read-only tools run without asking. Tools that can change data ask first unless you turn this off." Studio reads this from the tool's own MCP annotations: a tool that declares itself read-only starts with Ask before running off; every other tool starts with it on, because the MCP specification treats a tool that does not say it is read-only as one that can change data. A tool carries the badge Can change data unless it declares itself read-only or not destructive (the MCP specification treats an undeclared tool as destructive). Every tool starts with Agents may use on.

On the connector's page, Tools shows the same table. Refresh tools reads the server again: tools you already set keep your choices, new tools get the defaults, and tools the server no longer offers are listed as "No longer on the server". Save tool settings (vN) saves a new connector version. Switching a tool off, or turning Ask before running on, applies at once to every agent; switching a tool on, or turning asking off, reaches an agent when it uses the new version.

In chat and workflows​

The agent calls the connector's tools as its own tools. Each call appears as a tool call card titled "connector · tool", with its inputs and the start of its result.

A call to a tool that asks before running waits: the card reads "tool: waiting for your approval", and the step's card on the board, its inspector and your Inbox show "Allow tool on connector?" with the exact call (and Can change data unless the tool declares itself not destructive). Allow runs this one call with exactly these arguments; Deny refuses it and tells the agent, with your note; the card then reads Denied (Chat: files, previews and approvals). A call nobody decides on within 30 minutes is not run.

A large result arrives as a file: anything over about 24,000 characters is saved as a JSON file in the conversation's or run's workspace under _tool_output/mcp/, appears in Files, and the agent receives its first 4,000 characters and reads the rest from the file, in its own code when it needs to.

Nothing for the server is available in the agent's execution environment: no URL, header, token or key. Studio holds the credentials and makes every call.

Recipe: this documentation as a connector​

This site publishes a read-only MCP server at https://docs.alphaagent.prometheusrl.com/mcp. It needs no credentials and offers three tools, search, fetch and list_sections, each declared read-only, so none asks before running.

  1. Create Connector, type MCP Server; name it "Product documentation" and write a guide such as "Answers questions about AlphaAgent Studio and Organisations from the public documentation."
  2. MCP Server URL: https://docs.alphaagent.prometheusrl.com/mcp; Sign-in method: No authentication.
  3. Test Connection: "Connected to server; 3 tools found." Leave the three tools as they are. Discover Tools & Enrich Guide, then Accept & Use This Guide.
  4. Create Connector (v1), add it to an agent, and ask "How do I create a Snowflake connector?": it calls search, then fetch, and answers from the page. To use the server from other tools, see Connect your agent.

Notes​

  • Limits: streamable HTTP only; public hosts, or internal hosts in the approved ranges (never loopback, link-local, metadata or the deployment's own addresses); redirects not followed; 30 seconds per request by default; 12 credential rows; 64 tools enabled per connector; one tool result at most 25 MB; 200 connector tool calls per run (Limits and quotas).
  • After an upgrade, existing MCP connectors keep working without a change: agents call their tools directly and every tool is available, and tools that do not declare themselves read-only ask before running. The connector's page says "This connector was added before tools could be chosen here."; click Review tools, turn Ask before running off for the tools you trust, and Save tool settings.
  • A connector downloaded from a Library arrives as Needs a credential unless its sign-in method needs none. Click Add credential on its page, or for AWS IAM with an assumed role open Role setup, add this Studio's External ID to the role's trust policy and test (Data connectors).
  • An agent call refused for a reason the agent can act on reads, after "connector (tool): ", "This tool is not enabled for agents. The connector's owner can enable it.", "The server does not offer this tool any more.", "The server refused the arguments: …", "The tool returned an error: …", "The result is larger than 25 MB, more than Studio accepts from one call. Ask for less, for example a narrower range." or "This run reached its limit of 200 connector tool calls."
  • Discovery finds nothing useful: the server advertised no tools, or thin descriptions; edit the guide before accepting. Create Connector (v1) disabled after a passing test: run discovery and accept a guide.
  • A tool call fails in chat with a credential sentence: the credentials may have rotated. Open Update, enter the new values and save a new version.