Připojení přes MCP

Přes MCP zpřístupníte CODEXIS AI Agenta aplikaci, ve které pracujete. Připojený klient může spravovat projekty, agenty a chaty, posílat zprávy s přílohami a sledovat jejich zpracování. Pro připojení k hostovanému serveru potřebujete jeho URL a API klíč k účtu s aktivní licencí. Pro lokální stdio potřebujete také dostupný příkaz codexis-agent-cli.

Nastavení konkrétní aplikace najdete v návodu MCP v Claude a Codex. Níže jsou parametry serveru a chování nástrojů. Operace běží nad Codexis AI agent API v2 pod účtem vlastníka klíče a dotazy čerpají jeho kredity.

Lokální připojení přes stdioCopy Anchor Link

MCP klient spouští proces a komunikuje s ním přes standardní vstup a výstup. Výchozí transport je stdio.

codexis-agent-cli mcp serve

Procesu předejte přihlašovací údaje v proměnných prostředí, případně použijte profil uložený přes CLI. Adresu zadejte jako origin, například https://vm.codexis.ai; cestu k API doplňuje CLI.

• CODEXIS_AGENT_ENDPOINT string, adresa instance CODEXIS AI Agenta.
• CODEXIS_AGENT_API_KEY string, váš API klíč.

Následující JSON ukazuje obecné nastavení spouštěného procesu. Klientovi předejte command, args a env způsobem, který používá pro konfiguraci MCP serverů. Hodnotu api-VAS_KLIC nahraďte svým klíčem.

{
  "command": "codexis-agent-cli",
  "args": ["mcp", "serve"],
  "env": {
    "CODEXIS_AGENT_ENDPOINT": "https://vm.codexis.ai",
    "CODEXIS_AGENT_API_KEY": "api-VAS_KLIC"
  }
}

Pro připojení určené ke čtení přidejte --read-only. Server pak dovolí číst data a sledovat běžící odpověď; pokus o změnu vrátí chybu READ_ONLY. Totéž nastavíte proměnnou CODEXIS_AGENT_READ_ONLY=true.

codexis-agent-cli mcp serve --read-only

Připojení přes HTTPCopy Anchor Link

Hostované MCP má adresu https://vm.codexis.ai/mcp. V klientovi zadejte tuto URL a hlavičku X-Api-Key se svým API klíčem. Nastavení pro Claude a Codex popisuje samostatný návod.

Pro vlastní lokální HTTP server použijte tento příkaz. Server bude dostupný na http://127.0.0.1:3000/mcp.

codexis-agent-cli mcp serve \
  --transport http \
  --endpoint https://vm.codexis.ai

V MCP klientovi zvolte HTTP připojení, zadejte tuto URL a přidejte hlavičku X-Api-Key se svým API klíčem ke každému požadavku. Server používá klíč příchozího požadavku, takže každý klient pracuje pod svým účtem. Backendový origin můžete serveru předat i proměnnou CODEXIS_AGENT_ENDPOINT.

• --host string, volitelné, IP adresa nebo localhost, na které server poslouchá. Výchozí: 127.0.0.1.
• --port integer, volitelné, port serveru. Výchozí: 3000.
• --allowed-host string, volitelné, povolený hostname příchozí HTTP hlavičky Host, bez portu. Pro více názvů parametr zopakujte. Výchozí: localhost, 127.0.0.1 a [::1].
• --read-only boolean, volitelné, zapne režim čtení pro všechny klienty tohoto serveru.

Při zpřístupnění přes vlastní doménu nastavte odpovídající --allowed-host a HTTPS zajistěte před serverem reverzní proxy. API klíč přenášejte šifrovaným spojením.

První voláníCopy Anchor Link

Po připojení si klient načte katalog nástrojů přes MCP tools/list. K ověření účtu zavolejte identity_get s prázdnými argumenty. Ukázky v této části jsou parametry MCP volání tools/call.

{
  "name": "identity_get",
  "arguments": {}
}

Nástroje vracejí výsledek v structuredContent a současně jako JSON v textovém obsahu. Chyby operací mají isError: true a kód v structuredContent.error.code. Při neplatných parametrech může klient obdržet pouze textovou chybu v content; neznámý nástroj vrací protokolovou chybu.

Pro práci s uloženými daty použijte project_list, agent_list a chat_list. K vytvoření slouží project_create, agent_create a chat_create; každý z těchto typů má také nástroje pro detail, úpravu a smazání. Stránkované seznamy vracejí nextCursor, který při dalším volání předáte jako cursor se stejnými filtry.

Nový chat založíte pomocí chat_create. Můžete zadat agentId z agent_list nebo vybrat model z model_list. Odpověď obsahuje id chatu, které pak předáte jako chatId nástroji message_send. Pro instrukce konkrétního uloženého agenta předejte jeho ID také v poli agentIds při message_send.

Odeslání a navázání odpovědiCopy Anchor Link

message_send přijímá zejména tato pole.

• chatId string, UUID, povinné, ID existujícího chatu.
• message string, text zprávy. Pošlete text, přílohu nebo obojí.
• requestId string, UUID, volitelné, identifikátor konkrétního odeslání. Pro obnovení po přerušení si ho vytvořte a uložte před voláním.
• attachmentIds string[], volitelné, ID předem nahraných příloh.
• attachments object[], volitelné, přílohy k nahrání společně se zprávou.

Přijatá zpráva vrátí requestId, chatId, userMessageId a assistantMessageId. Hodnotu assistantMessageId použijte jako messageId při sledování. Pokud se spojení přeruší během odeslání, ověřte jeho stav přes message_request_get s původními chatId a requestId před dalším pokusem.

PřílohyCopy Anchor Link

Soubor předem nahrajete přes attachment_upload. V odpovědi najdete pole items s ID přílohy; to předáte do message_send.attachmentIds. Příloha se při odeslání přesune ke zprávě. Do té doby její metadata získáte přes attachment_get a odstranit ji můžete přes attachment_delete.

Malé přílohy můžete posílat přímo jako base64 přes oba transporty. Limit je 32 KiB dekódovaného obsahu na soubor. Celý HTTP požadavek má limit 64 KiB včetně JSON a base64, proto větší počet příloh nahrajte samostatnými voláními a zprávě předejte jejich ID.

Tento příklad nahraje soubor poznamka.txt s obsahem Hello a koncem řádku.

{
  "name": "attachment_upload",
  "arguments": {
    "source": {
      "name": "poznamka.txt",
      "base64": "SGVsbG8K"
    }
  }
}

Pro lokální soubory na macOS a Linuxu spusťte stdio server s povolenou složkou. Parametr --allow-path můžete zopakovat pro více složek.

mkdir -p podklady
codexis-agent-cli mcp serve --allow-path "$PWD/podklady"

Potom v attachment_upload.source.path předejte absolutní cestu k souboru z této složky. Stejný objekt s polem path přijímají i message_send.attachments a question_answer.attachments. Pro HTTP použijte inline obsah nebo ID přílohy předem nahrané přes CLI či REST API.

Průběžné odpovědiCopy Anchor Link

Jednorázový stav odpovědi získáte přes message_status. Průběh sledujte pomocí message_watch se stejnými chatId a messageId. Ukázková ID níže nahraďte hodnotami z přijaté zprávy.

{
  "name": "message_watch",
  "arguments": {
    "chatId": "3f8b1a20-77c4-4c19-8d2e-1b9a4e6f0c85",
    "messageId": "69de2470-09f4-43a1-a1dc-858ffad924a7",
    "deadlineMs": 25000
  },
  "_meta": {
    "progressToken": "odpoved-1"
  }
}

Když klient předá _meta.progressToken, dostává notifications/progress. Pole message obsahuje celý aktuální text odpovědi s citacemi, případně stav zpracování, než text vznikne. Zobrazený text při aktualizaci nahraďte novou hodnotou. Bez progressToken klient obdrží výsledný strukturovaný stav po skončení sledování.

deadlineMs je kladné celé číslo v milisekundách, výchozí 25000, nejvýše 600000. Sledování skončí při stavu completed, failed, stopped nebo waiting. Úspěšné dokončení potvrzuje execution.state s hodnotou completed. Po chybě WAIT_TIMEOUT znovu zavolejte message_watch se stejnými ID; vzdálené zpracování pokračuje.

Zrušení stdio volání nebo přerušení moderního HTTP streamu ukončuje pouze sledování. U starších HTTP klientů může sledování doběhnout do stanoveného limitu. Pro zastavení práce agenta zavolejte chat_stop s chatId a konkrétním messageId, potom výsledek ověřte přes message_status.

Otázky a automatizaceCopy Anchor Link

Stav waiting znamená, že agent čeká na reakci. Přes interaction_list a interaction_get načtěte otázku nebo návrh automatizace včetně toolCallId a revision. Při odpovědi předejte tyto hodnoty společně s chatId a messageId, aby se reakce vztahovala k přečtené verzi.

Na otázku odpovězte přes question_answer. Volby v poli selectedPositions jsou číslované od nuly; text doplňte do freeText. Přiložit můžete i soubory stejným způsobem jako ke zprávě.

O návrhu automatizace rozhodněte přes workflow_decide s hodnotou decision: RUN, REQUEST_CHANGES nebo CANCEL. Pro REQUEST_CHANGES přidejte feedback. Rozhodnutí se vztahuje k danému návrhu; pro zastavení celého běhu použijte chat_stop.

Průběh automatizace načtete přes workflow_list. Dílčí agenty a jejich zprávy zpřístupňují subagent_list, subagent_get a subagent_message_list. Historii hlavního chatu získáte přes chat_message_list a chat_message_get.

Kam pokračovatCopy Anchor Link

Ovládání přes CLI · REST API V2