MCP servers API
Create an MCP server and preview its tools.
Send exactly one connection mode. A backing proxy, or an inbound credential plus target plus target credential. The server URL is regional. Nested rules, filters, meters, overrides, alerts, and transforms are on those pages.
Endpoints
| Method | Path | What it does |
|---|---|---|
| GET | /api/clients/:clientId/mcps | List MCP servers |
| POST | /api/clients/:clientId/mcps | Create an MCP server |
| GET | /api/clients/:clientId/mcps/:mcpId | Read an MCP server |
| PUT | /api/clients/:clientId/mcps/:mcpId | Update an MCP server |
| DELETE | /api/clients/:clientId/mcps/:mcpId | Delete an MCP server |
| POST | /api/clients/:clientId/mcps/preview-tools | Preview tools before save |
| POST | /api/clients/:clientId/mcps/:mcpId/preview-tools | Preview tools for a saved server |
Create an MCP server
POST /api/clients/:clientId/mcps creates the server. This body uses a backing proxy. For direct mode, omit the proxy and send the inbound credential, target, and target credential instead.
Request
curl -X POST "https://api.requestrocket.com/api/clients/:clientId/mcps" \
-H "Authorization: u-your-token" \
-H "Content-Type: application/json" \
-d '{
"mcpName": "HTTPBin tools",
"mcpRegion": "us-east-2",
"mcpActive": true,
"mcpProxyId": "5d8a1c30-4e72-4b19-8f6a-0c3d9e7b1a25"
}'import axios from "axios";
const response = await axios.request({
method: "POST",
url: "https://api.requestrocket.com/api/clients/:clientId/mcps",
headers: {
"Authorization": "u-your-token",
"Content-Type": "application/json",
},
data: {
"mcpName": "HTTPBin tools",
"mcpRegion": "us-east-2",
"mcpActive": true,
"mcpProxyId": "5d8a1c30-4e72-4b19-8f6a-0c3d9e7b1a25"
}
});
console.log(response.status, response.data);import requests
response = requests.request(
"POST",
"https://api.requestrocket.com/api/clients/:clientId/mcps",
headers={
"Authorization": "u-your-token",
"Content-Type": "application/json",
},
data="{\n \"mcpName\": \"HTTPBin tools\",\n \"mcpRegion\": \"us-east-2\",\n \"mcpActive\": true,\n \"mcpProxyId\": \"5d8a1c30-4e72-4b19-8f6a-0c3d9e7b1a25\"\n}"
)
print(response.status_code, response.json())package main
import (
"fmt"
"io"
"net/http"
"strings"
)
func main() {
payload := strings.NewReader(`{
"mcpName": "HTTPBin tools",
"mcpRegion": "us-east-2",
"mcpActive": true,
"mcpProxyId": "5d8a1c30-4e72-4b19-8f6a-0c3d9e7b1a25"
}`)
req, _ := http.NewRequest("POST", "https://api.requestrocket.com/api/clients/:clientId/mcps", payload)
req.Header.Set("Authorization", "u-your-token")
req.Header.Set("Content-Type", "application/json")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(resp.StatusCode, string(body))
}import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Example {
public static void main(String[] args) throws Exception {
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.requestrocket.com/api/clients/:clientId/mcps"))
.method("POST", HttpRequest.BodyPublishers.ofString("{\n \"mcpName\": \"HTTPBin tools\",\n \"mcpRegion\": \"us-east-2\",\n \"mcpActive\": true,\n \"mcpProxyId\": \"5d8a1c30-4e72-4b19-8f6a-0c3d9e7b1a25\"\n}"))
.header("Authorization", "u-your-token")
.header("Content-Type", "application/json")
.build();
HttpResponse<String> response = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.statusCode());
System.out.println(response.body());
}
}Responses
{
"mcps": [
{
"userId": "0f8e6c1a-2b7d-4c3e-9a55-1d2e3f4a5b6c",
"clientId": "b3a1c7d2-5e44-4f0a-9c1e-7d2f8a6b1c90",
"parentId": "b3a1c7d2-5e44-4f0a-9c1e-7d2f8a6b1c90",
"mcpName": "HTTPBin tools",
"mcpRegion": "us-east-2",
"mcpActive": true,
"mcpNotes": null,
"mcpConfiguration": "b3a1c7d2-5e44-4f0a-9c1e-7d2f8a6b1c90/c5a9e013-8d27-4b61-a4f0-1e6c3b8d5a47",
"mcpCreatedAt": "2026-11-02T07:30:00.000Z",
"mcpUpdatedAt": "2026-11-02T07:30:00.000Z",
"mcpDefaultRuleEffect": "allow",
"mcpMaxRetries": null,
"mcpMaxBackoff": null,
"mcpProxyId": "5d8a1c30-4e72-4b19-8f6a-0c3d9e7b1a25",
"mcpProxyCredentialId": null,
"mcpTargetId": null,
"mcpTargetCredentialId": null
}
],
"message": "Success"
}{
"message": "mcpRegion is required"
}{
"Message": "User is not authorized to access this resource with an explicit deny in an identity-based policy"
}{
"message": "method / endpoint not supported"
}Returns an mcps array with message set to "Success".
Request body
Send a backing proxy in mcpProxyId, or send mcpProxyCredentialId, mcpTargetId, and mcpTargetCredentialId together. A backing proxy clears the direct fields.
| Parameter | Type | Required | Description |
|---|---|---|---|
mcpName | string | ✓ | Display name, 3–256 characters. |
mcpRegion | string | ✓ | Region that stores the server, such as us-east-2. It cannot be changed later. |
mcpProxyId | string | — | Backing proxy id. Sending this selects proxy mode. |
mcpProxyCredentialId | string | — | Inbound credential id for direct mode, or consumer_pool. |
mcpTargetId | string | — | Target id for direct mode. |
mcpTargetCredentialId | string | — | Target credential id for direct mode. |
mcpActive | boolean | — | When false, the server does not serve traffic. Defaults to true. |
mcpAlias | string | — | Lowercase letters and dashes. Stored in lowercase. |
mcpDefaultRuleEffect | string | — | "allow" or "deny". Defaults to "allow". |
mcpMaxRetries | number | — | Retry count. Maximum 10. |
mcpMaxBackoff | number | — | Retry wait ceiling. Maximum 30. |
mcpNotes | string | — | Free-text note. |
openapi | string or object | — | OpenAPI document as JSON text, YAML text, or an object. Tools are generated from it when tools is omitted. |
tools | object | — | Tool catalog with version 1 and a tools array. At most 200 tools. |
Returns an mcps array. The attributes match List MCP servers. sKey on the create response is the new server id.
Preview tools
POST /api/clients/:clientId/mcps/preview-tools returns the tool list a document would produce. The saved-server path is the same call under /mcps/:mcpId/preview-tools.
Request
curl -X POST "https://api.requestrocket.com/api/clients/:clientId/mcps/preview-tools" \
-H "Authorization: u-your-token" \
-H "Content-Type: application/json" \
-d '{
"openapi": "https://example.com/openapi.json"
}'import axios from "axios";
const response = await axios.request({
method: "POST",
url: "https://api.requestrocket.com/api/clients/:clientId/mcps/preview-tools",
headers: {
"Authorization": "u-your-token",
"Content-Type": "application/json",
},
data: {
"openapi": "https://example.com/openapi.json"
}
});
console.log(response.status, response.data);import requests
response = requests.request(
"POST",
"https://api.requestrocket.com/api/clients/:clientId/mcps/preview-tools",
headers={
"Authorization": "u-your-token",
"Content-Type": "application/json",
},
data="{\n \"openapi\": \"https://example.com/openapi.json\"\n}"
)
print(response.status_code, response.json())package main
import (
"fmt"
"io"
"net/http"
"strings"
)
func main() {
payload := strings.NewReader(`{
"openapi": "https://example.com/openapi.json"
}`)
req, _ := http.NewRequest("POST", "https://api.requestrocket.com/api/clients/:clientId/mcps/preview-tools", payload)
req.Header.Set("Authorization", "u-your-token")
req.Header.Set("Content-Type", "application/json")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(resp.StatusCode, string(body))
}import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Example {
public static void main(String[] args) throws Exception {
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.requestrocket.com/api/clients/:clientId/mcps/preview-tools"))
.method("POST", HttpRequest.BodyPublishers.ofString("{\n \"openapi\": \"https://example.com/openapi.json\"\n}"))
.header("Authorization", "u-your-token")
.header("Content-Type", "application/json")
.build();
HttpResponse<String> response = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.statusCode());
System.out.println(response.body());
}
}Responses
{
"tools": [
{
"operationKey": "getPing",
"name": "getPing",
"method": "GET",
"path": "/ping",
"enabled": true
}
],
"summary": {
"added": 1,
"updated": 0,
"protected": 0
},
"conflicts": [],
"message": "Success"
}{
"message": "Could not generate tools from the OpenAPI document"
}{
"Message": "User is not authorized to access this resource with an explicit deny in an identity-based policy"
}{
"message": "method / endpoint not supported"
}Returns tools, summary, conflicts, and message set to "Success".
Request body
| Parameter | Type | Required | Description |
|---|---|---|---|
openapi | string or object | ✓ | OpenAPI document as JSON text, YAML text, or an object. |
existingTools | object or array | — | Catalog to compare against. On /mcps/:mcpId/preview-tools, the stored catalog is used when this is omitted. |
mode | string | — | "merge" or "overwrite". Defaults to "merge". |
resetEnabled | boolean | — | When true, each tool's enabled flag is taken from the document. Defaults to false. |
removeOrphans | boolean | — | When true, generated tools missing from the document are dropped. Defaults to false. |
removeManualOrphans | boolean | — | When true, manual tools missing from the document are dropped. Defaults to false. |
Response attributes
| Attribute | Type | Description |
|---|---|---|
tools | array | The catalog the document would produce. Each tool includes operationKey, name, method, path, and enabled. |
summary.added | number | Tools added from the document. |
summary.updated | number | Tools updated from the document. |
summary.protected | number | Tools unchanged by the merge. |
summary.orphaned | number | Tools in the existing catalog but absent in the document. |
conflicts | array | Names that could not be merged cleanly. |
serverUrl | string or null | First servers[].url in the document, when present. |
message | string | "Success". |
List MCP servers
GET /api/clients/:clientId/mcps returns every MCP server for the organisation in one response. GET /api/clients/:clientId/mcps/:mcpId returns one server plus its tool catalog.
Response attributes
| Attribute | Type | Description |
|---|---|---|
mcps | array | One or more MCP server objects. |
mcps[].sKey | string | Server id. Pass this as mcpId on other endpoints. |
mcps[].pKey / parentId | string | Organisation id. |
mcps[].mcpName | string | Display name. |
mcps[].mcpRegion | string | Deployment region. |
mcps[].mcpActive | boolean | Whether the server serves traffic. |
mcps[].mcpProxyId | string or null | Backing proxy id when in proxy mode. |
mcps[].mcpProxyCredentialId | string or null | Inbound credential id when in direct mode, or consumer_pool. |
mcps[].mcpTargetId | string or null | Target id when in direct mode. |
mcps[].mcpTargetCredentialId | string or null | Target credential id when in direct mode. |
mcps[].mcpConfiguration | string | Storage prefix for the tool catalog and OpenAPI document. |
mcps[].mcpDefaultRuleEffect | string | "allow" or "deny". |
mcps[].mcpMaxRetries | number or null | Retry count. |
mcps[].mcpMaxBackoff | number or null | Retry wait ceiling. |
mcps[].mcpAlias | string or null | URL alias. |
mcps[].mcpNotes | string or null | Free-text note. |
mcps[].mcpCreatedAt | string | ISO 8601 creation time. |
mcps[].mcpUpdatedAt | string | ISO 8601 last update time. |
mcps[].referenceStatus | string | ok, missing_proxy, missing_credential, missing_target, or unsupported_credential_type. |
mcps[].tools | object | Stored tool catalog. Only on a single-server read. |
mcps[].openapi | object or null | Stored OpenAPI document. Only on a single-server read. |
message | string | "Success". |
Update an MCP server
PUT /api/clients/:clientId/mcps/:mcpId changes the fields you send. The region stays as it was created. Sending mcpProxyId switches the server to proxy mode and clears the direct credential and target ids.
Request body
All fields are optional. Omit a field to leave it unchanged.
| Parameter | Type | Required | Description |
|---|---|---|---|
mcpName | string | — | Display name, 3–256 characters. |
mcpActive | boolean | — | When false, the server does not serve traffic. |
mcpAlias | string | — | Lowercase letters and dashes. |
mcpNotes | string | — | Free-text note. |
mcpProxyId | string | — | Backing proxy id. Sending this selects proxy mode. |
mcpProxyCredentialId | string | — | Inbound credential id for direct mode, or consumer_pool. |
mcpTargetId | string | — | Target id for direct mode. |
mcpTargetCredentialId | string | — | Target credential id for direct mode. |
mcpDefaultRuleEffect | string | — | "allow" or "deny". |
mcpMaxRetries | number | — | Retry count. Maximum 10. |
mcpMaxBackoff | number | — | Retry wait ceiling. Maximum 30. |
openapi | string or object | — | Replaces the stored OpenAPI document. |
tools | object | — | Replaces the tool catalog. version must be 1. At most 200 tools. |
Returns an mcps array with message set to "MCP server updated successfully", plus connectionMode of "proxy" or "direct". The attributes match List MCP servers.
A direct server rejects a temporary target credential. Region mismatches and sending both a proxy and direct credentials return 400. The tool cap is 200.