/jentic

name: jentic
description: Calls third-party APIs through a Jentic One instance — governed, credential-managed access where the agent searches for an operation, inspects it, and executes it through an audited broker that holds the credentials (identity → discover → check access → execute). Applies when the user asks to call an external API or use a connected service — e.g. "find the vessel-tracking API and add it", "get rows from this Google Sheet", connect Slack, import/search/discover an API, integrate or automate a SaaS, pull data from a service, or call an external endpoint. Works over whichever Jentic surface the session has, the `jentic` MCP tools or the `jentic` CLI. Not for local-only work (editing code, finding files, adding a package/dependency, or questions with no external API call).
version: 7

Using Jentic

Jentic is an API broker: you discover operations across many APIs, then execute them through a single authenticated gateway without managing each API's credentials yourself. The same audited loop — identity → discover → check access → execute — is exposed over two surfaces. This document is the surface-neutral guide to the loop; the per-surface mechanics live in the `references/` files next to it. **Work out which session you are in first**, then load ONLY your lane's reference:

• **CLI session** — the `jentic` CLI is on PATH. Read `references/cli.md`

for every command, flag, exit code, and failure diagnosis.

• **MCP session** — your session has `jentic` MCP **tools** (`whoami`,

`search_apis`, `execute`, …). Read `references/mcp.md` for the tool surface, call shapes, envelopes, and recovery. (It also explains the stdio-vs-HTTP-mount tell — `get_started` present vs absent — and what each flavor can and cannot do.)

• For pitfalls, the command/tool cheatsheet, and verification checklists in

both lanes, read `references/recovery.md`.

Both lanes drive the same loop against the same backend. The `instance` stamp (`backend`/`host`/`instance_id`) on every MCP tool result — and the unauthenticated `GET /instance` endpoint — is the which-backend-am-I-on check; in a CLI session `jentic context view` reads the same facts.

When to Use

• You need to call a third-party API (Stripe, GitHub, Slack, …) but don't have

its SDK or credentials wired up.

• The user asks to **find, add, import, connect, or search for an API/tool**

("find the vessel-tracking API and add it", "get rows from this Google Sheet").

• You want to discover what operations exist for a capability ("create a

payment", "list pull requests") without reading raw OpenAPI specs.

• You are an agent that should drive real API calls through one audited broker.

Your session's Jentic surface — the `jentic` MCP tools or the `jentic` CLI — reaches the APIs connected to this deployment through the broker, which audits each call and resolves credentials server-side, so you never handle the raw secret.

Prerequisites

• A Jentic identity your human operator set up and a human approved — you

never mint your own. How the credential is attached differs by lane (the CLI attaches a token; an MCP client presents an OAuth grant or bearer key per request); you never see or handle the raw credential in either lane.

• A reachable Jentic deployment (control plane + broker). Reachability and

base-URL configuration are lane concerns — see your lane's reference file.

• **CLI session:** read `references/cli.md` before running commands — it is

the command, flag, and environment contract for this lane.

• **MCP session:** read `references/mcp.md` before calling tools — it is the

tool-surface and envelope contract for this lane.

Procedure

Each step below is shared doctrine — what to do and in what order. The exact commands (CLI) and tool calls (MCP) for every step are in `references/cli.md` and `references/mcp.md`; follow your session's lane through every step and never execute the other lane's verbs.

1. Confirm you have a valid identity

The exact commands (CLI) and tool calls (MCP) for this step and every step after it are in `references/cli.md` and `references/mcp.md`; follow your session's lane through every step and never execute the other lane's verbs.

You normally don't set up your own identity — your human operator connects this agent to a Jentic install out-of-band (via `jentic register`/`jentic setup` for a CLI machine, or by authorizing the MCP connection) and a human approves it. First, check your setup: run your lane's identity check (CLI `jentic doctor`; MCP `whoami`). If it reports a registered, approved identity with a usable credential, move on to step 2.

If it does not (no context, not registered, pending approval, or an auth error), **stop and relay to your operator** — registration and approval block on a human and cannot be completed by an autonomous agent. Your lane's reference names the exact recovery for each state.

2. Check what you can do, and start connecting what's missing

Your identity view (CLI `jentic whoami`; MCP `whoami`) lists your status, permissions, and credential bindings; each binding lists the APIs it **serves** (`serves: [{api_vendor, api_name, api_version}]`). This tells you exactly what you can already call. Combined with the catalog (what's available to add — step 3), it's your map of the workspace.

**Decide access from that view first — do NOT execute an operation just to see whether you have access.** A denied execute is a wasted round-trip; you can tell in advance:

• If a binding already **serves** the API you need → you have access. Skip

straight to inspect/execute.

• If **nothing** you're bound to serves it → you do **not** have access yet.

Start the connection (below) — or report the gap — **before** your first execute; do not "try execute and branch on the denial".

**Report once, richly — never thrash.** Work out the full access end-state up front — from your identity view, the catalog, and the task — and hand your operator **o