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.
| Server | Adresa | Za koga |
|---|---|---|
| Cifra | https://www.cifra.ba/mcp | Pojedinci s cifra.ba nalogom |
| Cifra Enterprise | https://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.
| Dokument | Adresa (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_idje HTTPS adresa vašeg metadata dokumenta) ili Dynamic Client Registration (RFC 7591) na/api/auth/oauth2/register. Klijenti s povratnom adresom nalocalhostili vlastitoj šemi registruju se kao nativni. - Tok: Authorization Code s PKCE (
S256). Pošaljiteresource(adresu MCP servera) u zahtjevu za autorizaciju i za token: token važi samo za taj server. - Scope:
openid profile email offline_access. Uzoffline_accessdobijate 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
401serror="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/mcpAlati
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
| Alati | Opis |
|---|---|
find_vehicle | Katalog marki i modela; izvedbe po godištu |
value_vehicle, revalue_report | Procjena i izvještaj u nalogu (troši dnevnu procjenu) |
get_market_prices, search_listings | Traž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_matches | Alarmi za oglase |
get_account, account_*, billing_details, billing_cancel* | Plan, profil, uređaji, povezani asistenti, pretplata |
send_feedback | Utisak 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.
isError: true u rezultatu alata.