# Jentic > Using Jentic - Skill: `jentic/jentic` (Agent Skill, multi-file: 4 files) - Install (CLI): `npx skillmds@latest add jentic/jentic` - Raw SKILL.md: https://api.skillmd.com/api/skills/jentic/jentic/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: jentic (https://skillmd.com/u/jentic) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/jentic/jentic --- # 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 → request 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") — treat these as Jentic tasks, not local-repo or generic tool-search tasks, even when you are running inside a code repository. - You want to discover what operations exist for a capability ("create a payment", "list pull requests") instead of reading raw OpenAPI specs. - You are an agent that should drive real API calls through one audited broker. Reach for your session's Jentic surface — the `jentic` MCP tools or the `jentic` CLI — **before** generic tool discovery (`ToolSearch`) or hand-rolling HTTP calls: the broker is the single audited path to external APIs and handles credentials for you. ## 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 request access if needed Your identity view (CLI `jentic access whoami`; MCP `whoami`) lists your status, scopes, 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; file no request. - If **nothing** you're bound to serves it → you do **not** have access yet. Provision it **before** your first execute — do not "try execute and branch on the denial". **File once, richly — never thrash.** Work out the full access end-state up front — from your identity view, the catalog, and the task — and file it as **one composite request** (CLI `jentic access request`; MCP `request_access`) covering every API the job needs, so the human decides in one sitting. Always include a reason: a human reviews it before approving and your reason is shown to them — a clear one-liner ("fetch the user's open PRs to summarise them") is what gets you approved faster. Never file duplicate or per-operation requests, and don't withdraw-and-refile to tweak a proposal. Granting is always a human action — you file and wait, you never approve yourself. Be honest about the terminal states: **denied** → read the items' `decision_reason` to learn *why* before giving up; **partially approved** → proceed only with what was actually granted. #### Proposing permission rules from the spec A provisioning plan is your chance to propose the credential's auth type and its permission rules as a **first pass** — a human reviews and edits them before approving. Do the work up front: inspect the operations you intend to call (step 4's lane verb) to read the methods, paths, and declared security schemes; pick the auth type from what the spec declares (`bearer`, `api_key`, `basic`, `oauth2`), or `none` if the API needs no credential; then translate the user's plain-English intent into concrete `allow`/`deny` rules with `methods`/`path` — "Read everything, write only to the prod board" becomes `[{"effect":"allow","methods":["GET"],"path":".*"}, {"effect":"allow","methods":["POST","PUT"],"path":"/boards/prod/.*"}]`. An `allow` rule must constrain at least one of `methods`/`path`/`operations`. **Be honest at the enforcement seam.** The broker matches a rule against the request's HTTP method, URL path, and OpenAPI operation id — **never the request body**. An intent that hinges on a body field ("only allow messages to the #general channel" when the channel is a POST-body field) **cannot be enforced** by these rules. Don't propose a rule that silently won't fire — say so, and offer the real choices: allow the operation broadly (the human accepts the wider grant), deny the operation entirely, or allow it and record the constraint as instructions you follow yourself (unenforced). Also sanity-check your proposal before filing: rules evaluate first-match-wins, so an early broad `allow` shadows every rule after it, and a rule set that contradicts the intent you stated in your reason will confuse the human reviewing it. You never enter the credential secret and you never approve — the human fills the secret in the dashboard and grants the plan. You propose; they decide. A plain credential-binding request (filed by API reference) is only the **last mile** — use it when a credential serving the API already exists (e.g. an operator provisioned one) and you just need to be bound to it. When nothing serves the API yet, a provisioning plan is the right first move; a bare bind request would auto-deny with `decision_reason: "No credential covers API ; provision a credential for it first"` — that is the signal to file the provisioning plan instead. ### 3. Find an operation (import first, then search) Operation search only sees operations that have been **imported into this deployment's local registry**. On a fresh install the registry is empty, so a search returns `{"data": []}` until you import something. **Import before you search** — if the user already named the API/vendor (e.g. "Google Sheets"), go straight to the catalog; don't search an empty registry first and waste a call. The discovery order is: browse the public catalog for an importable API → import the one you want (auto-promotes to live) → search the local registry. Importing an **already-cataloged** API is gated on `catalog:import`, which an approved agent holds **by default** — no access request needed. Just run the import. Re-importing an API that is already there is safe — the registry state **converges** either way — but the surfaces report the duplicate differently (a success on the HTTP mount, a dead-letter "identical content already exists" error on the stdio server and the CLI); your lane's reference names the exact shape. Treat it as "already there" — don't retry, and don't file an access request for a made-up "catalog read" scope: reading the registry and importing a cataloged API need no grant. **Before concluding "the data is gone", confirm which backend you're on.** If APIs or credentials you *know* existed appear missing — or IDs look unfamiliar — you may be talking to a **different** backend than you expect: a hosted (`remote`) install and a `local` self-hosted one have independent registries and credentials, and each surface in your session can be bound to a different one. Check the `instance` stamp (MCP) or `jentic context view` / `GET /instance` (CLI) and repoint the client at the right base URL rather than importing/searching again. ### 4. Inspect the operation's contract Resolve an operation to its method, path, parameters, and schemas before calling it (CLI `jentic inspect`; MCP `inspect_operation`). Pass the `operation_id` from the search hit, or a `METHOD URL` pair. Always inspect before you execute — the contract names the parameters and the security requirements you'll propose rules against. ### 5. Execute through the broker Send the request through the Jentic broker (CLI `jentic execute`; MCP `execute` / `execute_read`). The broker is a transparent forward proxy, so the target is the **full upstream URL** (scheme + host + path), not a host-relative path. Reference an `operation_id` from the search/inspect step — the surface fills in the upstream URL for you — or pass `METHOD:URL` directly. The broker authenticates you and injects the stored upstream credential server-side; credentials never pass through your session. A held or async execution does not answer inline: it returns a **job envelope** (`{job_id, status, …}`). Poll the job until its status is terminal — and **never re-send the original call while a job is pending**: approval happens out-of-band, and re-sending duplicates the side effect. A denied or failed execute carries a coded recovery (the CLI's stderr `agent_directive` + exit codes; MCP's coded error envelopes). Follow the directive/envelope rather than assuming which recovery applies — the denial taxonomy and its per-code recoveries are in your lane's reference. Diagnose a failure by its symptom, not by assuming access: transport failures (DNS/TLS/refused) and denials recover differently. ## Quick Reference - The loop, in either lane: identity check → decide access from your bindings (file ONE composite request if short) → catalog import → registry search → inspect → execute through the broker. - CLI session: the full command cheatsheet is in `references/cli.md` (and `jentic --help` is always current); MCP session: the 9 mount tools / 10 stdio tools with one-line whens are in `references/mcp.md`. - Both cheatsheets, side by side with pitfalls and verification, are in `references/recovery.md`. ## Pitfalls - Executing before the agent is registered/approved fails — there is no usable identity. Run your lane's identity check and relay the recovery to your operator; nothing you can call completes an approval. - An empty search result (`{"data": []}`) usually means **nothing is imported yet**, not that you lack access. Go through the catalog, then search again. - **Don't execute to test access.** Your identity view already tells you what your bindings **serve**; if the API you need isn't there, file the provisioning plan and wait. The recovery directive is a fallback for surprises, not a discovery step. - You file and wait for access; you can't approve your own requests. - **Verify which backend you're talking to before diagnosing "missing" APIs or credentials** — compare `instance` stamps (see step 3) and stick to one surface for the whole task. - The lane-specific pitfall lists (broker-URL/DNS diagnosis, stopped instances, job-pending rules, envelope caveats) are in `references/recovery.md` — read your lane's section before debugging. ## Verification - Your lane's identity check answers with a registered, approved identity. - After importing an API from the catalog, a registry search for something in that API returns at least one result. - A known-allowed read executed through the broker returns a 2xx response. - The lane-specific checklists (exact commands and tool calls) are in `references/recovery.md`.