Last updated

Guide: connecting agents and clients

Mirrored from iblai/ontology Β· docs/guides/connect-agents.md. This page is generated β€” edit it in the repository, not here.

Every server has one endpoint on the platform's ontology server, https://<host>/<platform>/<slug>/mcp, speaking MCP over streamable HTTP. A console hosted elsewhere (the pages-only build) shows the server's second address, https://<host>/iblai/<platform>/<slug>/mcp, which answers the same. The examples below use the host ontology.university.edu, the platform acme and the server institution. Anything that speaks MCP can use it, provided it can reach the host and presents a credential of that platform that the server accepts (permissions.md).

Server Β· Connect
Server Β· Connect

ibl.ai OS agents

Deploying a server writes its config and starts it on the platform's server. It registers nothing on ibl.ai. An agent gets the server when you attach it:

  1. Open the server in the console and press Attach under Connect, or press Attach a Server to an Agent on Agents.

  2. Pick the agent and the toolsets it may use. The console then, with your ibl.ai session:

    • makes sure each toolset has its role and its Ontology: <toolset> policy,
    • creates an API key limited to those policies,
    • registers the server on ibl.ai for that agent alone, with the key as Api-Token,
    • turns on the agent's MCP tool with that server.

    If a step fails, the steps before it are undone and the message says what was undone.

  3. Verify from the agent: ask "what tools do you have from institution?" and then a real question. The call appears under the server's Activity tab.

The agent only ever talks to ibl.ai; ibl.ai calls https://<host>/<platform>/<slug>/mcp on your server, which must be reachable on 443 from ibl.ai's egress (network.md).

Claude Desktop and Claude Code

Both read a mcpServers map. The person must reach the host (on the VPN, if it sits behind one) and hold an API key that reaches the server's toolsets: MCP Gateway β†’ New MCP Server (or Edit Server) β†’ Authentication β†’ Issue Token creates one limited to the ticked toolsets and shows it once.

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "institution": {
      "url": "https://ontology.university.edu/acme/institution/mcp",
      "headers": { "Authorization": "Api-Token <token>" }
    }
  }
}

Claude Code:

claude mcp add --transport http institution https://ontology.university.edu/acme/institution/mcp \
  --header "Authorization: Api-Token <token>"

With an Entra auth service on the server, the client also sends the person's ID token in the header the runtime expects (entra_token for a service named entra); the runtime verifies it itself.

Codex CLI

~/.codex/config.toml:

[mcp_servers.institution]
url = "https://ontology.university.edu/acme/institution/mcp"
http_headers = { Authorization = "Api-Token <token>" }

Keep the token out of the file if you can: put it in an environment variable and reference it the way your Codex version supports (bearer_token_env_var on recent releases, which sends Authorization: Bearer; the gateway accepts it).

Cursor, Windsurf, other editors

Same shape as Claude Desktop: a url plus an Authorization header. Editors that only support stdio can bridge with mcp-remote:

{
  "mcpServers": {
    "institution": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://ontology.university.edu/acme/institution/mcp",
        "--header",
        "Authorization: Api-Token <token>"
      ]
    }
  }
}

Your own code

Python, official MCP SDK:

from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

URL = "https://ontology.university.edu/acme/institution/mcp"
AUTH = {"Authorization": "Api-Token " + os.environ["ONTOLOGY_TOKEN"]}

async with streamablehttp_client(URL, headers=AUTH) as (read, write, _):
    async with ClientSession(read, write) as s:
        await s.initialize()
        tools = await s.list_tools()
        rows = await s.call_tool("at_risk_students", {"term": "2026-FA"})

Smoke test with cURL:

curl -sS -X POST https://ontology.university.edu/acme/institution/mcp \
  -H "Authorization: Api-Token $ONTOLOGY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Browser-based agents and apps

claude.ai, os.ibl.ai and your own web apps call from a browser and send an Origin header. Add each origin under Allowed Origins on the server, or the gateway refuses the call before it looks at the token.

What a caller sees

  • tools/list returns only the tools in the toolsets the caller's grants reach. Two people with different policies see different lists from the same URL.
  • Tool descriptions carry the certified definition of the term ("Student = a person admitted to and enrolled in β‰₯1 program"), which is what makes agents pick the right tool.
  • ask_question (when included) accepts natural language, answers with certified SQL, and returns the SQL and the provenance alongside the rows.

Troubleshooting

ResponseMeaningFix
403, origin not allowedbrowser origin not on the server's listadd it under Allowed Origins and deploy again
403, host not allowedthe address's host name is not on the server's listadd it, or *.name, under Allowed Hosts and deploy again
refused over plain HTTPthe credential did not arrive over HTTPScall over HTTPS; the proxy must send X-Forwarded-Proto
401credential missing, expired or revokedissue a new key
ibl.ai's refusal, in its own wordsthe credential belongs to another platformuse a key issued on the platform in the address
403, no toolsetcredential valid but reaches no toolsetadd the toolset's Ontology: policy to the key or its group
JSON-RPC error -32003the tool is outside the toolsets the caller reachesgrant the policy of the toolset that holds it
429over 120 requests or 30 tool calls a minuteslow down; the limit is per caller
503ibl.ai did not answer the grant checkretry; nothing was kept
503, ONTOLOGY_PLATFORM is not setthe server has an engine but names no platformthe server's operator sets it (install.md)
403, serves another platformits ONTOLOGY_PLATFORM names another platformuse the address of that platform's own server
404, the console's pagesthe address is a pages-only console's, not a serveruse https://<host>/<platform>/<slug>/mcp
timeout from an ibl.ai agentibl.ai egress not allowed inboundfirewall rule for ibl.ai egress on 443
works with cURL, not from Claude Desktopclient not on the VPNconnect to the VPN first

Copyright Β© ibl.ai | support@iblai.zendesk.com