Configuring Tools for Catalog Registration

after discovering available tools, add them to your agent catalog registration json step 1 run discovery python scripts/list mcp tools py format catalog step 2 select required tools choose only the tools your agent needs { "tools" \[ { "name" "servicenow mcp", "operations" \[ "servicenow get all incidents", "servicenow search incidents" ] }, { "name" "bridge mcp", "operations" \[ "bridge execute query", "bridge list domains", "bridge list tables", "bridge get table details" ] } ] } step 3 update registration json copy the tools configuration to your agent catalog registration json file using mcp tools in your agent calling tools with mcpclient import os from bridge agent sdk import mcpclient \# initialize client — base url is optional (sdk resolves from kaif host) mcp = mcpclient( agent payload=state get("platform context", {}), ) \# call a tool result = await mcp call tool( tool name="servicenow get all incidents", arguments={"limit" 10} ) \# process result incidents = result get("data", \[]) tool naming convention mcp tool names follow the pattern pattern example servicenow servicenow get all incidents bridge bridge execute query azure azure keyvault aiops aiops ask me anything error handling try result = await mcp call tool(tool name="servicenow search incidents", arguments={"limit" 10}) if "error" in result logger error(f"mcp tool error {result\['error']}") return {"error" result\["error"]} return result get("data", \[]) except exception as e logger exception(f"mcp call failed ") raise mcp wire protocol (json rpc 2 0) the bridge mcp server uses the json rpc 2 0 protocol while the sdk's mcpclient handles this for you, understanding the wire format is essential for debugging and writing test scripts listing tools tools/list curl s x post "$bridge mcp server url" \\ h "authorization bearer $token" \\ h "content type application/json" \\ d '{ "jsonrpc" "2 0", "id" 1, "method" "tools/list", "params" {} }' | jq ' result tools | length' response structure { "jsonrpc" "2 0", "id" 1, "result" { "tools" \[ { "name" "servicenow search incidents", "description" "search for incidents ", "inputschema" { "type" "object", "properties" , "required" \[ ] } } ] } } calling a tool tools/call curl s x post "$ ?tenant id=$ \&account id=$ " \\ h "authorization bearer $token" \\ h "content type application/json" \\ h "accept application/json" \\ h "x instance id $deployment name" \\ h "x route version v3" \\ d '{ "jsonrpc" "2 0", "id" 1, "method" "tools/call", "params" { "name" "servicenow search incidents", "arguments" { "search term" "inc0010001", "search fields" \["number"] } } }' common mistake sending a flat payload like {"tool name" " ", "arguments" } will return 422 unprocessable entity you must use the json rpc envelope with jsonrpc, method, and params fields required headers for mcp calls when calling mcp tools (either directly or via the sdk), the following http headers are required header required value purpose authorization yes bearer \<iam token> authentication — obtained from /api/iam/v4/identity/token content type yes application/json request body format x instance id yes your deployment name (e g , inc enrichment deploy v1) routes the call to the correct agent deployment x route version yes v3 critical — tells the mcp gateway to use v3 routing without this header you will get 403 — agent instance not found in default collection accept recommended application/json response format the x route version v3 header this is the most commonly missed header the sdk sets it automatically, but when writing test scripts or curl commands you must include it headers = { "authorization" f"bearer ", "content type" "application/json", "accept" "application/json", "x instance id" deployment name, # your deployment name "x route version" "v3", # ← critical — do not omit } without this header , the mcp gateway falls back to the default routing collection and returns { "detail" "agent instance not found in default collection", "status code" 403 } query parameters when making direct http calls, append tenant and account ids as query parameters post ?tenant id= \&account id= the sdk's mcpclient appends these automatically (you can see it in the logs internal route adding query params \['tenant id', 'account id']) testing mcp tools method 1 discovery script (recommended first step) always start by discovering what tools are actually available \# list all tools grouped by mcp server python scripts/list mcp tools py \# filter to a specific server python scripts/list mcp tools py filter servicenow \# export full schemas to json python scripts/list mcp tools py output available tools json format raw method 2 get full tool schemas create scripts/get tool schema py to inspect exact inputschema of tools \#!/usr/bin/env python3 """get the full input schema for specific mcp tools """ import os, json, requests from dotenv import load dotenv load dotenv() kaif host = os getenv("kaif host") service api key = os getenv("service api key") mcp url = os getenv("bridge mcp server url") \# 1 get token token = requests post( f" /api/iam/v4/identity/token", json={"apikey" service api key}, headers={"content type" "application/json"}, timeout=30, ) json() get("token") \# 2 list tools (json rpc 2 0) resp = requests post( mcp url, headers={ "content type" "application/json", "authorization" f"bearer ", }, json={"jsonrpc" "2 0", "id" 1, "method" "tools/list", "params" {}}, timeout=60, ) tools = resp json() get("result", {}) get("tools", \[]) \# 3 filter and print (change the prefix to inspect other servers) for t in tools if "servicenow" in t get("name", "") print(json dumps(t, indent=2)) print(" ") method 3 direct tool call (test script) test a specific tool call with all required headers \#!/usr/bin/env python3 """test a single mcp tool call with full headers """ import os, json, requests from dotenv import load dotenv load dotenv() kaif host = os getenv("kaif host") service api key = os getenv("service api key") account id = os getenv("bridge account id") mcp url = os getenv("bridge mcp server url") deployment name = "inc enrichment deploy v1" # ← your deployment name \# 1 authenticate token = requests post( f" /api/iam/v4/identity/token", json={"apikey" service api key}, headers={"content type" "application/json"}, timeout=30, ) json()\["token"] \# 2 build request headers = { "authorization" f"bearer ", "content type" "application/json", "accept" "application/json", "x instance id" deployment name, # routes to your deployment "x route version" "v3", # ← critical } payload = { "jsonrpc" "2 0", "id" 1, "method" "tools/call", "params" { "name" "servicenow search incidents", "arguments" { "search term" "inc0010001", "search fields" \["number"], }, }, } full url = f" ?tenant id= \&account id= " \# 3 call resp = requests post(full url, headers=headers, json=payload, timeout=30) print(f"status ") print(f"body {json dumps(resp json(), indent=2)}") method 4 curl one liner \# get token token=$(curl s x post "$kaif host/api/iam/v4/identity/token" \\ h "content type application/json" \\ d "{\\"apikey\\" \\"$service api key\\"}" | jq r ' token') \# call tool curl s x post "$ ?tenant id=$ \&account id=$ " \\ h "authorization bearer $token" \\ h "content type application/json" \\ h "accept application/json" \\ h "x instance id inc enrichment deploy v1" \\ h "x route version v3" \\ d '{ "jsonrpc" "2 0", "id" 1, "method" "tools/call", "params" { "name" "bridge execute query", "arguments" { "query" "select number, short description from \\"itsm\\" incident limit 5" } } }' | jq troubleshooting 422 unprocessable entity — wrong payload format status 422 body {"detail" "request body is not valid json rpc 2 0"} cause you sent a flat json payload instead of json rpc 2 0 format wrong (flat) {"tool name" "bridge execute query", "arguments" {"query" " "}} correct (json rpc 2 0) { "jsonrpc" "2 0", "id" 1, "method" "tools/call", "params" { "name" "bridge execute query", "arguments" {"query" " "} } } 403 forbidden "agent instance not found in default collection" {"detail" "agent instance not found in default collection", "status code" 403} cause missing x route version v3 header solution add the header to your request headers\["x route version"] = "v3" 403 forbidden "tool not allowed for profile" {"detail" "tool not allowed for profile 'default'", "status code" 403} cause the tool name you're calling does not exist on the mcp server, or it is not assigned to your deployment profile solution 1 run python scripts/list mcp tools py to see all available tools 2 verify the exact tool name (e g , servicenow search incidents, not servicenow get ticket) 3 ensure the tool is listed in your deployment registration json under mcp tools authentication failures (401) ✗ authentication failed 401 cause invalid or expired service api key solution 1 verify service api key in your env file 2 regenerate the key from bridge platform admin 3 ensure the key has mcp access permissions mcp server unreachable ✗ request failed connection refused cause incorrect bridge mcp server url or network issues solution 1 verify the mcp url is correct for your account 2 check vpn connection (for bridge dev mode) 3 url format https // bridge kyndryl com/kaif/v2/mcp/tools missing x instance id header if x instance id is missing or wrong, the mcp call may succeed at the http level but tools will not be routed to your deployment, resulting in 403 or empty results solution ensure x instance id matches your deployment name exactly headers\["x instance id"] = "inc enrichment deploy v1" # must match deployment registration json → name best practices 1\ minimize tool selection only request tools your agent actually uses // ✅ good specific tools "operations" \["servicenow search incidents"] // ❌ bad requesting all tools "operations" \["servicenow get all incidents", "servicenow create incident", "servicenow search incidents", "servicenow update incident", ] 2\ cache discovery results run discovery once and save results python scripts/list mcp tools py output docs/available mcp tools json 3\ document required tools add comments in your registration json { "tools" \[ { "name" "servicenow mcp", "operations" \[ "servicenow search incidents" // used by incident lookup node ] } ] } 4\ test tools locally first before catalog registration, test tools in bridge dev mode \# in your agent, add debug logging result = await mcp call tool(tool name="servicenow search incidents", arguments={"search term" "test"}) print(f"tool result {json dumps(result, indent=2)}")