curl --request POST \
--url https://api.example.com/api/settings/mcp/{settings_key} \
--header 'Content-Type: application/json' \
--header 'X-Session-API-Key: <api-key>' \
--data '
{
"args": [
"<string>"
],
"auth": {
"strategy": "none"
},
"command": "<string>",
"cwd": "<string>",
"description": "<string>",
"enabled": true,
"env": {},
"headers": {},
"icon": "<string>",
"keep_alive": true,
"sse_read_timeout": 123,
"timeout": 123,
"url": "<string>"
}
'import requests
url = "https://api.example.com/api/settings/mcp/{settings_key}"
payload = {
"args": ["<string>"],
"auth": { "strategy": "none" },
"command": "<string>",
"cwd": "<string>",
"description": "<string>",
"enabled": True,
"env": {},
"headers": {},
"icon": "<string>",
"keep_alive": True,
"sse_read_timeout": 123,
"timeout": 123,
"url": "<string>"
}
headers = {
"X-Session-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-Session-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
args: ['<string>'],
auth: {strategy: 'none'},
command: '<string>',
cwd: '<string>',
description: '<string>',
enabled: true,
env: {},
headers: {},
icon: '<string>',
keep_alive: true,
sse_read_timeout: 123,
timeout: 123,
url: '<string>'
})
};
fetch('https://api.example.com/api/settings/mcp/{settings_key}', 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.example.com/api/settings/mcp/{settings_key}",
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([
'args' => [
'<string>'
],
'auth' => [
'strategy' => 'none'
],
'command' => '<string>',
'cwd' => '<string>',
'description' => '<string>',
'enabled' => true,
'env' => [
],
'headers' => [
],
'icon' => '<string>',
'keep_alive' => true,
'sse_read_timeout' => 123,
'timeout' => 123,
'url' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-Session-API-Key: <api-key>"
],
]);
$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.example.com/api/settings/mcp/{settings_key}"
payload := strings.NewReader("{\n \"args\": [\n \"<string>\"\n ],\n \"auth\": {\n \"strategy\": \"none\"\n },\n \"command\": \"<string>\",\n \"cwd\": \"<string>\",\n \"description\": \"<string>\",\n \"enabled\": true,\n \"env\": {},\n \"headers\": {},\n \"icon\": \"<string>\",\n \"keep_alive\": true,\n \"sse_read_timeout\": 123,\n \"timeout\": 123,\n \"url\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Session-API-Key", "<api-key>")
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.example.com/api/settings/mcp/{settings_key}")
.header("X-Session-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"args\": [\n \"<string>\"\n ],\n \"auth\": {\n \"strategy\": \"none\"\n },\n \"command\": \"<string>\",\n \"cwd\": \"<string>\",\n \"description\": \"<string>\",\n \"enabled\": true,\n \"env\": {},\n \"headers\": {},\n \"icon\": \"<string>\",\n \"keep_alive\": true,\n \"sse_read_timeout\": 123,\n \"timeout\": 123,\n \"url\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/settings/mcp/{settings_key}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-Session-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"args\": [\n \"<string>\"\n ],\n \"auth\": {\n \"strategy\": \"none\"\n },\n \"command\": \"<string>\",\n \"cwd\": \"<string>\",\n \"description\": \"<string>\",\n \"enabled\": true,\n \"env\": {},\n \"headers\": {},\n \"icon\": \"<string>\",\n \"keep_alive\": true,\n \"sse_read_timeout\": 123,\n \"timeout\": 123,\n \"url\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"agent_settings": {
"mcp_config": {},
"agent_kind": "openhands",
"schema_version": 2
},
"conversation_settings": {},
"llm_api_key_is_set": true,
"active_agent_profile_id": "<string>",
"active_meta_profile": "<string>",
"active_profile": "<string>",
"misc_settings": {}
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"ctx": {},
"input": "<unknown>"
}
]
}Create Mcp Server
Create one named MCP server without replacing an existing map entry.
curl --request POST \
--url https://api.example.com/api/settings/mcp/{settings_key} \
--header 'Content-Type: application/json' \
--header 'X-Session-API-Key: <api-key>' \
--data '
{
"args": [
"<string>"
],
"auth": {
"strategy": "none"
},
"command": "<string>",
"cwd": "<string>",
"description": "<string>",
"enabled": true,
"env": {},
"headers": {},
"icon": "<string>",
"keep_alive": true,
"sse_read_timeout": 123,
"timeout": 123,
"url": "<string>"
}
'import requests
url = "https://api.example.com/api/settings/mcp/{settings_key}"
payload = {
"args": ["<string>"],
"auth": { "strategy": "none" },
"command": "<string>",
"cwd": "<string>",
"description": "<string>",
"enabled": True,
"env": {},
"headers": {},
"icon": "<string>",
"keep_alive": True,
"sse_read_timeout": 123,
"timeout": 123,
"url": "<string>"
}
headers = {
"X-Session-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-Session-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
args: ['<string>'],
auth: {strategy: 'none'},
command: '<string>',
cwd: '<string>',
description: '<string>',
enabled: true,
env: {},
headers: {},
icon: '<string>',
keep_alive: true,
sse_read_timeout: 123,
timeout: 123,
url: '<string>'
})
};
fetch('https://api.example.com/api/settings/mcp/{settings_key}', 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.example.com/api/settings/mcp/{settings_key}",
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([
'args' => [
'<string>'
],
'auth' => [
'strategy' => 'none'
],
'command' => '<string>',
'cwd' => '<string>',
'description' => '<string>',
'enabled' => true,
'env' => [
],
'headers' => [
],
'icon' => '<string>',
'keep_alive' => true,
'sse_read_timeout' => 123,
'timeout' => 123,
'url' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-Session-API-Key: <api-key>"
],
]);
$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.example.com/api/settings/mcp/{settings_key}"
payload := strings.NewReader("{\n \"args\": [\n \"<string>\"\n ],\n \"auth\": {\n \"strategy\": \"none\"\n },\n \"command\": \"<string>\",\n \"cwd\": \"<string>\",\n \"description\": \"<string>\",\n \"enabled\": true,\n \"env\": {},\n \"headers\": {},\n \"icon\": \"<string>\",\n \"keep_alive\": true,\n \"sse_read_timeout\": 123,\n \"timeout\": 123,\n \"url\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Session-API-Key", "<api-key>")
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.example.com/api/settings/mcp/{settings_key}")
.header("X-Session-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"args\": [\n \"<string>\"\n ],\n \"auth\": {\n \"strategy\": \"none\"\n },\n \"command\": \"<string>\",\n \"cwd\": \"<string>\",\n \"description\": \"<string>\",\n \"enabled\": true,\n \"env\": {},\n \"headers\": {},\n \"icon\": \"<string>\",\n \"keep_alive\": true,\n \"sse_read_timeout\": 123,\n \"timeout\": 123,\n \"url\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/settings/mcp/{settings_key}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-Session-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"args\": [\n \"<string>\"\n ],\n \"auth\": {\n \"strategy\": \"none\"\n },\n \"command\": \"<string>\",\n \"cwd\": \"<string>\",\n \"description\": \"<string>\",\n \"enabled\": true,\n \"env\": {},\n \"headers\": {},\n \"icon\": \"<string>\",\n \"keep_alive\": true,\n \"sse_read_timeout\": 123,\n \"timeout\": 123,\n \"url\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"agent_settings": {
"mcp_config": {},
"agent_kind": "openhands",
"schema_version": 2
},
"conversation_settings": {},
"llm_api_key_is_set": true,
"active_agent_profile_id": "<string>",
"active_meta_profile": "<string>",
"active_profile": "<string>",
"misc_settings": {}
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"ctx": {},
"input": "<unknown>"
}
]
}Authorizations
Path Parameters
Body
One MCP server in the settings DataModel.
- MCPNoneAuthCredential
- MCPApiKeyAuthCredential
- MCPBearerAuthCredential
- MCPBasicAuthCredential
- MCPHeaderAuthCredential
- MCPOAuthAuthCredential
Show child attributes
Show child attributes
1Whether this server is exposed to the agent. A disabled server stays fully configured -- including its secrets -- but is skipped when MCP tools are created and when servers are forwarded to an ACP subprocess.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
stdio, http, sse, streamable-http 1Response
Successful Response
Response model for GET /api/settings.
Contains the full settings payload including agent configuration, conversation settings, active LLM profile, miscellaneous frontend-owned settings, and a flag indicating whether an LLM API key is set.
The agent_settings and conversation_settings fields are raw dicts
because the server controls secret serialization via context. Use the
typed accessor methods for validation:
Example::
response = SettingsResponse.model_validate(api_response.json())
agent = response.get_agent_settings() # Returns AgentSettingsConfig
conv = response.get_conversation_settings() # Returns ConversationSettings
misc_settings is an opaque container for frontend-owned data that the
agent-server persists but does not interpret — see the docstring of
:class:PersistedSettings.misc_settings.
Show child attributes
Show child attributes
Stable id of the currently active AgentProfile, if one is set.
Name of the currently active meta-profile, if one is selected.
Name of the currently active LLM profile, if one is selected.
Was this page helpful?

