Configuring Tools for Catalog Registration

add tool to catalog registration after discovering available tools, add them to your agent catalog registration json run discovery python scripts/list mcp tools py format catalog 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" ] } ] } 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 the following 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 {{e}}") 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 "${{bridge mcp server url}}?tenant id=${{account id}}\&account 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 {{token}}", "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 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") get token token = requests post( f"{{kaif host}}/api/iam/v4/identity/token", json={"apikey" service api key}, headers={"content type" "application/json"}, timeout=30, ) json() get("token") list tools (json rpc 2 0) resp = requests post( mcp url, headers={ "content type" "application/json", "authorization" f"bearer {{token}}", }, json={"jsonrpc" "2 0", "id" 1, "method" "tools/list", "params" {}}, timeout=60, ) tools = resp json() get("result", {}) get("tools", \[]) 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 authenticate token = requests post( f"{{kaif host}}/api/iam/v4/identity/token", json={"apikey" service api key}, headers={"content type" "application/json"}, timeout=30, ) json()\["token"] build request headers = { "authorization" f"bearer {{token}}", "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"{{mcp url}}?tenant id={{account id}}\&account id={{account id}}" call resp = requests post(full url, headers=headers, json=payload, timeout=30) print(f"status {{resp status code}}") 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 "${{bridge mcp server url}}?tenant id=${{bridge account id}}\&account id=${{bridge 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