Connect an MCP server with OAuth for the organization
curl --request POST \
--url https://api.runaether.dev/mcp-servers/{mcpServerID}/org-connection/oauth \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"url": "<string>",
"return_to": "<string>"
}
'import requests
url = "https://api.runaether.dev/mcp-servers/{mcpServerID}/org-connection/oauth"
payload = {
"url": "<string>",
"return_to": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({url: '<string>', return_to: '<string>'})
};
fetch('https://api.runaether.dev/mcp-servers/{mcpServerID}/org-connection/oauth', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.runaether.dev/mcp-servers/{mcpServerID}/org-connection/oauth",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'url' => '<string>',
'return_to' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.runaether.dev/mcp-servers/{mcpServerID}/org-connection/oauth"
payload := strings.NewReader("{\n \"url\": \"<string>\",\n \"return_to\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.runaether.dev/mcp-servers/{mcpServerID}/org-connection/oauth")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"url\": \"<string>\",\n \"return_to\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.runaether.dev/mcp-servers/{mcpServerID}/org-connection/oauth")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"url\": \"<string>\",\n \"return_to\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"authorization_url": "<string>"
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}{
"code": "mcp_server_key_invalid",
"error": "<string>"
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}MCP Servers
Connect an MCP server with OAuth for the organization
Starts the organization's own OAuth connection to an MCP server, granted with the calling admin's consent, or its reconnection, and returns the authorization URL to send the admin's browser to.
Use this tool when you need to:
- Connect an OAuth server once for the whole organization, so projects can use the org credential policy
- Reconnect the organization's OAuth connection after it needs_reauth (authorizer_left, invalid_grant, insufficient_scope or revoked)
Examples:
- POST /mcp-servers/{mcpServerID}/org-connection/oauth {"url": "https://mcp.acme.dev/mcp"}
- POST /mcp-servers/6f1c2a9e-3b7d-4c55-9a2e-0d8b1f4e7c21/org-connection/oauth {"url": "https://mcp.acme.dev/mcp", "return_to": "/connect/acme"}
Hints:
- url is required, the server's URL as the catalog showed it (409 mcp_connection_server_changed when it is now another or the server is local); return_to is optional, as for startMcpServerOAuth (422 mcp_server_return_to_invalid for another server's connect page).
- The browser comes back to the web app, which finishes with finishMcpServerOAuth in the same admin's session within 15 minutes; the grant is stored only while that admin is still an owner or admin.
- Projects may then use the org credential policy for the server (updateMcpServer, enableProjectMcpServer).
- Refused with 422 mcp_connection_oauth_not_accepted, mcp_oauth_not_advertised, mcp_oauth_pkce_unsupported, mcp_oauth_app_required (putMcpOAuthApp), mcp_oauth_registration_failed or the probe's code, as startMcpServerOAuth is.
- Use startMcpServerOAuth instead for the caller's own connection, and connectOrgMcpServer for a server that takes an API key.
- Org admins only: owners and admins of the server's organization; a member is refused with 403 control_forbidden, a viewer or billing member with 403 org_role_insufficient, and a server the caller cannot see is 404. Refused with 503 when the membership check is unavailable.
- An agent host's grant is refused with 403 agent_host_route_not_allowed.
POST
/
mcp-servers
/
{mcpServerID}
/
org-connection
/
oauth
Connect an MCP server with OAuth for the organization
curl --request POST \
--url https://api.runaether.dev/mcp-servers/{mcpServerID}/org-connection/oauth \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"url": "<string>",
"return_to": "<string>"
}
'import requests
url = "https://api.runaether.dev/mcp-servers/{mcpServerID}/org-connection/oauth"
payload = {
"url": "<string>",
"return_to": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({url: '<string>', return_to: '<string>'})
};
fetch('https://api.runaether.dev/mcp-servers/{mcpServerID}/org-connection/oauth', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.runaether.dev/mcp-servers/{mcpServerID}/org-connection/oauth",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'url' => '<string>',
'return_to' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.runaether.dev/mcp-servers/{mcpServerID}/org-connection/oauth"
payload := strings.NewReader("{\n \"url\": \"<string>\",\n \"return_to\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.runaether.dev/mcp-servers/{mcpServerID}/org-connection/oauth")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"url\": \"<string>\",\n \"return_to\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.runaether.dev/mcp-servers/{mcpServerID}/org-connection/oauth")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"url\": \"<string>\",\n \"return_to\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"authorization_url": "<string>"
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}{
"code": "mcp_server_key_invalid",
"error": "<string>"
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}Authorizations
Body
application/json
Where the web app's callback page sends the browser with the outcome once it has finished the connection: the Aether mobile app's deep link, or the server's own connect page (/connect/); refused (400) for another server's. Omitted, the page returns to the Integrations tab.
Pattern:
^(aether://mcp-connected|/connect/[a-z][a-z0-9_-]{0,31})$