APIAI agenti

MCP i AI agenti

Cifra kao MCP server za AI agente i asistente: adrese, OAuth, alati i kada koristiti MCP, a kada REST API.

Pregled

Cifra ima dva udaljena MCP servera (Model Context Protocol, Streamable HTTP). Oba rade s prijavom osobe preko OAuth 2.1: agent radi u ime čovjeka, s njegovim planom ili njegovom ulogom u kompaniji.

ServerAdresaZa koga
Cifrahttps://www.cifra.ba/mcpPojedinci s cifra.ba nalogom
Cifra Enterprisehttps://enterprise.cifra.ba/mcpČlanovi kompanija na Cifra Enterprise

MCP ili REST API

  • MCP kad čovjek razgovara s asistentom (Claude, ChatGPT, vaš agent s ljudskim korisnikom): prijava osobe, alati opisani za model, kartice s rezultatom.
  • REST API za sistem-sistem integracije bez čovjeka: API ključ, kvote ugovora, webhookovi, masovne procjene, OpenAPI. Počnite s Brzi početak.

Autorizacija

Serveri slijede MCP specifikaciju autorizacije. Zahtjev bez tokena dobija 401 s WWW-Authenticate: Bearer resource_metadata=…; klijent odatle nalazi sve ostalo.

DokumentAdresa (cifra.ba; Enterprise isto na svom domenu)
Protected Resource Metadata (RFC 9728)/.well-known/oauth-protected-resource/mcp
Authorization Server Metadata (RFC 8414)/.well-known/oauth-authorization-server/api/auth
OpenID Connect Discovery/.well-known/openid-configuration/api/auth
  • Registracija klijenta: Client ID Metadata Document (preporučeno: client_id je HTTPS adresa vašeg metadata dokumenta) ili Dynamic Client Registration (RFC 7591) na /api/auth/oauth2/register. Klijenti s povratnom adresom na localhost ili vlastitoj šemi registruju se kao nativni.
  • Tok: Authorization Code s PKCE (S256). Pošaljite resource (adresu MCP servera) u zahtjevu za autorizaciju i za token: token važi samo za taj server.
  • Scope: openid profile email offline_access. Uz offline_access dobijate refresh token (30 dana, rotira se pri svakoj upotrebi).
  • Token: JWT, sat vremena. Enterprise token važi za jednu kompaniju, koju osoba odabere pri prijavi.
  • Opoziv: kad osoba prekine vezu ili kompanija isključi asistente, server odmah vraća 401 s error="invalid_token"; ponovite autorizaciju.

Povezivanje klijenta

claude mcp add --transport http cifra https://www.cifra.ba/mcp
claude mcp add --transport http cifra-enterprise https://enterprise.cifra.ba/mcp

Alati

Svaki alat ima title i anotacije readOnlyHint, destructiveHint i openWorldHint (uvijek false: alati rade samo nad Cifrinim podacima i nalogom osobe). Rezultat ima tekst za model (content) i iste podatke strukturirano (structuredContent).

Cifra

AlatiOpis
find_vehicleKatalog marki i modela; izvedbe po godištu
value_vehicle, revalue_reportProcjena i izvještaj u nalogu (troši dnevnu procjenu)
get_market_prices, search_listingsTražene cijene modela; oglasi u prodaji uz Cifrinu vrijednost
list_reports, get_report, report_*Izvještaji: provjera po broju, javni/privatni, prodajna cijena, ocjena, brisanje
list_listing_alerts, create_listing_alert, update_listing_alert, delete_listing_alert, alert_matchesAlarmi za oglase
get_account, account_*, billing_details, billing_cancel*Plan, profil, uređaji, povezani asistenti, pretplata
send_feedbackUtisak timu Cifre

Cifra Enterprise

Sve radnje platforme, grupisane prefiksom: valuation_*, bulk_*, check_*, vehicle_*, alert_*, radar_*, residual_*, inventory_*, widget_*, graphic_*, model_*, team_*, company_*, account_*, api_*, webhook_*, uz find_vehicle, value_vehicle, bulk_create i pregledne alate (account_overview, search_valuations, valuation_details, vehicles_overview, market_overview, residual_value, inventory_overview, vehicle_check). Kompanija sa svim proizvodima ima oko 170 alata; lista zavisi od ugovora i uloge osobe (tools/list vraća samo dostupne). Klijentima s ograničenjem broja alata (npr. Cursor) uključite samo potrebne. Detalji: AI asistenti.

Kartice (MCP Apps)

value_vehicle, get_report i get_market_prices imaju _meta.ui.resourceUri = "ui://cifra/card-v1.html": domaćini koji podržavaju MCP Apps (Claude, ChatGPT) prikazuju karticu s vrijednošću i rasponom ili cijenama po godištu. Kartica ne učitava ništa izvana; ostali klijenti koriste tekst i structuredContent.

Ograničenja

  • Procjene troše plan osobe (cifra.ba) ili ugovor kompanije (Enterprise), kao u aplikaciji; Enterprise ima i ograničenje od 30 procjena u minuti po kompaniji.
  • Za veće količine i automatizaciju bez čovjeka koristite REST API: Masovna procjena.
Greške su opisane riječima koje model može prenijeti korisniku (npr. iskorištene procjene, nepoznat model, proizvod nije u ugovoru), kao isError: true u rezultatu alata.