Crie uma ferramenta MCP útil
Defina nome, descrição e esquema de entrada para que clientes descubram e usem sua ferramenta com segurança.
- Escolher uma capacidade pequena e útil para expor
- Escrever uma descrição clara e esquemas JSON de entrada e saída
- Validar entradas no servidor antes de executar a ação
A definição de uma ferramenta é tudo o que o modelo sabe sobre ela; por isso, na prática, faz parte do prompt. Ela pode incluir:
name— identificador único no servidor, com 1 a 128 letras, números,_,-ou.(por exemplo,get_weatherouadmin.tools.list);title— nome de exibição opcional para as pessoas;description— o que a ferramenta faz, quando usá-la e quais efeitos pode causar;inputSchema— objeto JSON Schema que descreve os argumentos;outputSchema— esquema opcional para resultados estruturados;annotations— indicações opcionais sobre o comportamento, explicadas na próxima lição.
O esquema orienta clientes e modelos, mas não substitui a validação de cada chamada no servidor.
1{
2 "name": "get_forecast",
3 "title": "Previsão do tempo",
4 "description": "Retorna a previsão diária do tempo para uma cidade nos próximos 1 a 7 dias. Somente leitura.",
5 "inputSchema": {
6 "type": "object",
7 "properties": {
8 "city": {
9 "type": "string",
10 "description": "Nome da cidade, por exemplo, \"Lisboa\"",
11 "minLength": 2
12 },
13 "days": {
14 "type": "integer",
15 "minimum": 1,
16 "maximum": 7
17 },
18 "units": {
19 "type": "string",
20 "enum": [
21 "celsius",
22 "fahrenheit"
23 ]
24 }
25 },
26 "required": [
27 "city"
28 ],
29 "additionalProperties": false
30 },
31 "outputSchema": {
32 "type": "object",
33 "properties": {
34 "city": {
35 "type": "string"
36 },
37 "highs": {
38 "type": "array",
39 "items": {
40 "type": "number"
41 }
42 }
43 },
44 "required": [
45 "city",
46 "highs"
47 ]
48 }
49}Experimente
Até 15 XPExperimente um esquema de entrada
Veja como o servidor reage aos argumentos recebidos do modelo. Escolha um exemplo e depois escreva seus próprios argumentos. Quais erros viram falhas de execução (isError: true) que o modelo pode ler e corrigir? O que acontece se a solicitação nem sequer for JSON válido? E se "additionalProperties": false fosse removido: "color": "red" seria aceito?
Definição da ferramenta compartilhada pelo servidor (tools/list)
{
"name": "get_forecast",
"description": "Retorna a previsão do tempo diária de uma cidade para os próximos 1 a 7 dias.",
"inputSchema": {
"type": "object",
"properties": {
"city": {
"type": "string",
"minLength": 2
},
"days": {
"type": "integer",
"minimum": 1,
"maximum": 7
},
"units": {
"type": "string",
"enum": [
"celsius",
"fahrenheit"
]
}
},
"required": [
"city"
],
"additionalProperties": false
}
}Resposta do servidorSucesso
{
"jsonrpc": "2.0",
"id": 7,
"result": {
"resultType": "complete",
"content": [
{
"type": "text",
"text": "Previsão para Lisboa: 3 dias de sol."
}
],
"isError": false
}
}Resultados estruturados
O resultado inclui content, uma lista de itens de texto, imagem, áudio ou recurso para o modelo e a pessoa usuária. Se a ferramenta declarar um outputSchema, o resultado também precisa incluir structuredContent compatível com esse esquema, que programas podem usar diretamente. Para clientes antigos, a especificação sugere retornar o mesmo JSON também como conteúdo de texto.
1{
2 "jsonrpc": "2.0",
3 "id": 5,
4 "result": {
5 "resultType": "complete",
6 "content": [
7 {
8 "type": "text",
9 "text": "{\"city\": \"Lisboa\", \"highs\": [24, 26, 23]}"
10 }
11 ],
12 "structuredContent": {
13 "city": "Lisboa",
14 "highs": [
15 24,
16 26,
17 23
18 ]
19 }
20 }
21}Principais conclusões
Ferramentas pequenas e específicas são mais fáceis de selecionar e proteger.
Descreva claramente entradas, resultados e efeitos colaterais.
Valide cada chamada no servidor; se declarar
outputSchema, retornestructuredContentcompatível.
Quiz da aula
7 perguntas · aprovação com 5 acertos · até 50 XP
Ao passar, você conclui a aula e mantém sua sequência. As perguntas erradas voltarão em sessões de revisão.
Pratique: crie um servidor MCP
Escreva código Python no editor e execute os testes com exemplos. O Python roda localmente no navegador usando WebAssembly.
Valide argumentos da ferramenta
A primeira linha contém um inputSchema JSON com propriedades do tipo texto, inteiro ou booleano e uma lista de campos obrigatórios. A segunda linha contém os argumentos. Imprima valid ou liste primeiro os campos obrigatórios ausentes e depois os argumentos com tipo incorreto. Em Python, True é um int, mas não vale como inteiro neste exercício.
- Argumentos válidos
- Campo ausente e tipo incorreto
- Booleano não é inteiro
O Python é executado em um ambiente isolado no navegador, com limite de 60 segundos. O runtime é carregado pelo CDN do Pyodide; seu código permanece neste navegador.
Confira nomes de ferramentas
Leia um nome por linha até o fim da entrada. Imprima NAME ok se tiver de 1 a 128 caracteres e usar somente letras ASCII, números, _, - e .; caso contrário, imprima NAME invalid. Compare o nome exato, sem a quebra de linha.
- Exemplos válidos da especificação
- Caracteres inválidos
O Python é executado em um ambiente isolado no navegador, com limite de 60 segundos. O runtime é carregado pelo CDN do Pyodide; seu código permanece neste navegador.
Dúvidas sobre esta lição
Travou em algum ponto? Pergunte. Descobriu algo? Compartilhe. Explicar também é uma ótima forma de aprender.
Carregando publicações…