Add or Replace an MCP Tool

POST

ai-gateway

mcp-servers

{id}

tools

Upsert an MCP tool row

curl --request POST \
  --url https://api.knoxcall.com/v1/ai-gateway/mcp-servers/{id}/tools \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "tool_name": "get_weather",
  "description": "Current weather for a city",
  "enabled": true
}
'

import requests

url = "https://api.knoxcall.com/v1/ai-gateway/mcp-servers/{id}/tools"

payload = {
    "tool_name": "get_weather",
    "description": "Current weather for a city",
    "enabled": True
}
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({
    tool_name: 'get_weather',
    description: 'Current weather for a city',
    enabled: true
  })
};

fetch('https://api.knoxcall.com/v1/ai-gateway/mcp-servers/{id}/tools', 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.knoxcall.com/v1/ai-gateway/mcp-servers/{id}/tools",
  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([
    'tool_name' => 'get_weather',
    'description' => 'Current weather for a city',
    'enabled' => true
  ]),
  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.knoxcall.com/v1/ai-gateway/mcp-servers/{id}/tools"

	payload := strings.NewReader("{\n  \"tool_name\": \"get_weather\",\n  \"description\": \"Current weather for a city\",\n  \"enabled\": true\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.knoxcall.com/v1/ai-gateway/mcp-servers/{id}/tools")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"tool_name\": \"get_weather\",\n  \"description\": \"Current weather for a city\",\n  \"enabled\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.knoxcall.com/v1/ai-gateway/mcp-servers/{id}/tools")

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  \"tool_name\": \"get_weather\",\n  \"description\": \"Current weather for a city\",\n  \"enabled\": true\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "tenant_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "mcp_server_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "tool_name": "<string>",
    "route_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "description": "<string>",
    "input_schema": {},
    "enabled": true,
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z"
  },
  "meta": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Creates the tool row, or replaces it if one with the same name already exists. Recording a tool here does not by itself expose it. A tool is reachable only when it is also in the server’s allowed_tools — the allowlist is the control, and this endpoint is the catalogue. Requires the update capability on ai_gateway. See the control-plane overview for authentication, the {data, meta} envelope, pagination and error types.

Authorizations

Authorization

string

header

required

OAuth 2.1 authentication — recommended for new integrations. Access tokens (kc_ prefix) are minted at the root-host token endpoint https://api.knoxcall.com/oauth/token and passed as Authorization: Bearer <access_token>. Public clients must use PKCE with the authorization_code grant; confidential clients may use client_credentials. The first-party SDKs and the knoxcall login CLI handle token minting, caching, refresh, and DPoP for you.

Path Parameters

string<uuid>

required

The MCP server UUID.

Body

application/json

tool_name

string

required

description

string | null

input_schema

object

enabled

boolean

default:true

Response

The upserted tool row.

data

object

A tool metadata row. It does not widen what the server advertises — that is the intersection of allowed_tools, the upstream's real tools and the token's tool scope.

Show child attributes

meta

object

Metadata included with every API response.

Show child attributes

Upsert an MCP tool row

curl --request POST \
  --url https://api.knoxcall.com/v1/ai-gateway/mcp-servers/{id}/tools \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "tool_name": "get_weather",
  "description": "Current weather for a city",
  "enabled": true
}
'

import requests

url = "https://api.knoxcall.com/v1/ai-gateway/mcp-servers/{id}/tools"

payload = {
    "tool_name": "get_weather",
    "description": "Current weather for a city",
    "enabled": True
}
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({
    tool_name: 'get_weather',
    description: 'Current weather for a city',
    enabled: true
  })
};

fetch('https://api.knoxcall.com/v1/ai-gateway/mcp-servers/{id}/tools', 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.knoxcall.com/v1/ai-gateway/mcp-servers/{id}/tools",
  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([
    'tool_name' => 'get_weather',
    'description' => 'Current weather for a city',
    'enabled' => true
  ]),
  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.knoxcall.com/v1/ai-gateway/mcp-servers/{id}/tools"

	payload := strings.NewReader("{\n  \"tool_name\": \"get_weather\",\n  \"description\": \"Current weather for a city\",\n  \"enabled\": true\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.knoxcall.com/v1/ai-gateway/mcp-servers/{id}/tools")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"tool_name\": \"get_weather\",\n  \"description\": \"Current weather for a city\",\n  \"enabled\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.knoxcall.com/v1/ai-gateway/mcp-servers/{id}/tools")

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  \"tool_name\": \"get_weather\",\n  \"description\": \"Current weather for a city\",\n  \"enabled\": true\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "tenant_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "mcp_server_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "tool_name": "<string>",
    "route_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "description": "<string>",
    "input_schema": {},
    "enabled": true,
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z"
  },
  "meta": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Overview

Routes

Secrets

Clients

Environments

API Keys

Webhooks

Ephemeral Proxy

AI Gateway

Audit Logs

Account

Tenant KMS

Secret Store Migrations

Changelog

Add or Replace an MCP Tool

Authorizations

Path Parameters

Body

Response