> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orkeia.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Criar Ferramenta

> Cria uma nova ferramenta no ambiente.

## Endpoint

`POST https://gateway.orkeia.ai/tools`

**Autenticação**\
Requer cabeçalho `authorization:  <seu_token>`.

## Corpo da Requisição (JSON)

> O serviço espera um **wrapper** com a propriedade `tool`. (O `environment` é tratado no servidor.)\
> **Atenção:** o campo `type` **não** existe nesta interface. Utilize os campos definidos em `Tool` (abaixo).

```json theme={null}
{
  "tool": {
    "name": "Minha Ferramenta",
    "description": "Descrição da ferramenta",
    "code": "export async function run(input){ return { ok: true }; }",
    "entryFunctionName": "run",
    "sectors": ["engineering", "legal"],
    "publisher": "Orkeia",
    "enabled": true,
    "environments": ["prod"],
    "mcp": {
      "url": "https://tools.orkeia.ai/my-tool",
      "transport": "sse"
    }
  }
}
```

## Exemplo (cURL)

```bash theme={null}
curl -X POST "https://gateway.orkeia.ai/tools"   -H "authorization:  <seu_token>"   -H "Content-Type: application/json"   -d '{
    "tool": {
      "name": "Minha Ferramenta",
      "description": "Descrição da ferramenta",
      "code": "export async function run(input){ return { ok: true }; }",
      "entryFunctionName": "run",
      "sectors": ["engineering", "legal"],
      "publisher": "Orkeia",
      "enabled": true,
      "environments": ["prod"],
      "mcp": {
        "url": "https://tools.orkeia.ai/my-tool",
        "transport": "sse"
      }
    }
  }'
```

## Respostas

### Response - Success

```json response theme={null}
{
  "status": "OK",
  "data": { "id": "TOOL_123456" }
}
```

### 500 — Server Error

```json theme={null}
{
  "status": "ERROR",
  "code": "server/error",
  "data": null
}
```

### 400 — Client Error

```json theme={null}
{
  "status": "ERROR",
  "code": "client/error",
  "data": null
}
```

## Interface de Referência (`Tool`)

```ts theme={null}
export interface Tool {
  id?: string;
  name: string;
  description: string;
  code?: string;
  entryFunctionName?: string;
  sectors: string[];
  publisher: string;
  enabled: boolean;
  environments: string[];
  mcp?: {
    url: string;
    transport: 'sse' | 'streamable-http';
  };
}
```

## Campos

| Nome              | Tipo                         | Obrigatório | Descrição                                                 | Exemplo                                |
| ----------------- | ---------------------------- | ----------- | --------------------------------------------------------- | -------------------------------------- |
| id                | string                       | Não         | Identificador único (retornado pelo backend).             | `TOOL_123456`                          |
| name              | string                       | Sim         | Nome da ferramenta.                                       | `Minha Ferramenta`                     |
| description       | string                       | Sim         | Descrição curta sobre a funcionalidade.                   | `Executa operações de integração`      |
| code              | string                       | Não         | Código fonte executável da ferramenta (quando aplicável). | `export async function run(){...}`     |
| entryFunctionName | string                       | Não         | Nome da função exportada no `code` que será invocada.     | `run`                                  |
| sectors           | string\[]                    | Sim         | Setores autorizados a utilizar a ferramenta.              | `["engineering","legal"]`              |
| publisher         | string                       | Sim         | Publicador/organização responsável.                       | `Orkeia`                               |
| enabled           | boolean                      | Sim         | Indica se a ferramenta está habilitada.                   | `true`                                 |
| environments      | string\[]                    | Sim         | Ambientes em que a ferramenta está disponível.            | `["prod","staging"]`                   |
| mcp               | objeto                       | Não         | Configuração para uso via Model Context Protocol (MCP).   | `{ "url": "...", "transport": "sse" }` |
| mcp.url           | string                       | Não         | URL do servidor MCP.                                      | `https://tools.orkeia.ai/my-tool`      |
| mcp.transport     | `'sse' \| 'streamable-http'` | Não         | Tipo de transporte MCP suportado.                         | `sse`                                  |