MCP Tools Reference: classroommcp.googleapis.com

Ferramenta: list_courses

Lista os cursos do usuário com os detalhes (seção, sala, matéria, anos escolares, descrição, metas de aprendizado, estado e função do usuário). Use esse método como o principal ponto de entrada para descobrir cursos e recuperar os IDs deles. Os cursos geralmente têm o mesmo título. Por isso, use a seção para diferenciá-los. Retorna apenas cursos ATIVOS, a menos que courseState esteja definido (por exemplo, ARQUIVADO).

Para vincular o usuário a uma turma no app da Web do Google Sala de Aula, use https://classroom.google.com/c/{course_id} (mural) ou https://classroom.google.com/w/{course_id}/t/all (página "Atividades"). Use os IDs exatamente como retornados. Nunca tente adivinhar ou modificar esses valores.

O exemplo de código a seguir mostra como usar curl para chamar a ferramenta MCP list_courses.

Solicitação curl
curl --location 'https://classroommcp.googleapis.com/mcp/v1' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "list_courses",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Esquema de entrada

Solicitação para listar cursos.

ListCoursesRequest

Representação JSON
{
  "courseState": enum (State),
  "createdDateRange": {
    object (DateRange)
  },
  "timeZone": string,
  "titleContains": string,
  "pageSize": integer,
  "pageToken": string
}
Campos
courseState

enum (State)

Opcional. Filtrar por estado do curso. O valor padrão é ACTIVE.

createdDateRange

object (DateRange)

Opcional. Filtre por período de datas de criação.

timeZone

string

Obrigatório. O fuso horário da IANA do usuário (por exemplo, "America/Los_Angeles"). As datas nesta solicitação são interpretadas nele, e as datas na resposta são formatadas nele, correspondendo ao que o usuário vê no Google Sala de Aula.

titleContains

string

Opcional. Filtra o título por substring que não diferencia maiúsculas de minúsculas.

pageSize

integer

Opcional. Controla o tamanho da página. O padrão é 10, e o máximo é 50.

pageToken

string

Opcional. Token para paginação.

DateRange

Representação JSON
{
  "startDate": string,
  "endDate": string
}
Campos
startDate

string

Início inclusivo do período (formato: AAAA-MM-DD).

endDate

string

Fim do intervalo (formato: AAAA-MM-DD).

Estado

Estados de um curso.

Tipos enumerados
STATE_UNSPECIFIED Estado não especificado.
ACTIVE Estado ativo.
ARCHIVED Estado arquivado.
PROVISIONED Estado provisionado.

Esquema de saída

Resposta para listar cursos.

ListCoursesResponse

Representação JSON
{
  "courses": [
    {
      object (Course)
    }
  ],
  "nextPageToken": string
}
Campos
courses[]

object (Course)

A lista de cursos.

nextPageToken

string

O token da próxima página.

Curso

Representação JSON
{
  "id": string,
  "title": string,
  "role": enum (Role),
  "creationDate": string,
  "state": enum (State),
  "section": string,
  "room": string,
  "subject": string,
  "gradeLevels": string,
  "description": string,
  "learningGoals": [
    {
      object (LearningGoal)
    }
  ]
}
Campos
id

string

Identificador. Identificador do curso.

title

string

Título do curso.

role

enum (Role)

Papel do usuário neste curso.

creationDate

string

Data de criação do curso (formato: AAAA-MM-DD). Fica vazio se a data de criação não for conhecida.

state

enum (State)

Apenas saída. Estado do curso.

section

string

Opcional. nesta seção do curso.

room

string

Opcional. Sala do curso.

subject

string

Opcional. Assunto do curso.

gradeLevels

string

Opcional. Anos escolares do curso.

description

string

Opcional. Descrição do curso.

learningGoals[]

object (LearningGoal)

Apenas saída. Metas de aprendizado anexadas a este curso.

LearningGoal

Representação JSON
{
  "id": string,
  "type": enum (Type),
  "standardCode": string,
  "title": string,
  "documentTitle": string
}
Campos
id

string

Apenas saída. ID da meta de aprendizado. Para anexar um padrão, use um id de search_course_standards (não standardCode).

type

enum (Type)

Apenas saída. O tipo de meta de aprendizado.

standardCode

string

Apenas saída. Código padrão (por exemplo, "NY-2.NBT.4"). Preenchido apenas para padrões.

title

string

Apenas saída. Descrição da declaração para padrões ou título legível por humanos para habilidades.

documentTitle

string

Apenas saída. Nome do documento do currículo. Preenchido apenas para padrões.

Papel

Papéis de um usuário em um curso.

Tipos enumerados
ROLE_UNSPECIFIED Papel não especificado.
TEACHER Função de professor.
COTEACHER Função de professor auxiliar.
STUDENT Função de estudante.
INVITED_OR_INACTIVE Função convidada ou inativa.

Estado

Estados de um curso.

Tipos enumerados
STATE_UNSPECIFIED Estado não especificado.
ACTIVE Estado ativo.
ARCHIVED Estado arquivado.
PROVISIONED Estado provisionado.

Tipo

O tipo de meta de aprendizado.

Tipos enumerados
TYPE_UNSPECIFIED Tipo de meta de aprendizado não especificado.
STANDARD Um padrão de aprendizado de um currículo acadêmico.
SKILL Uma habilidade que representa um conceito ou competência educacional. Somente um professor pode adicionar ou remover habilidades no Google Sala de Aula.

Anotações de ferramentas

As anotações de ferramentas são enviadas aos clientes do MCP para descrever o risco básico de uma determinada ferramenta. A maioria dos clientes trata essas dicas como não confiáveis, mas elas podem ser usadas para decidir quando um pedido de confirmação pode ser enviado a um usuário.

Além da string de título, as seguintes dicas booleanas são definidas:

  • readOnlyHint: se for verdadeiro, a ferramenta não vai modificar o ambiente. (Padrão: falso).
  • destructiveHint: se for verdadeiro, a ferramenta poderá realizar ações destrutivas. Se for falso, a ferramenta só poderá realizar ações aditivas. Padrão: verdadeiro.
  • idempotentHint: se for verdadeiro, chamar a ferramenta repetidamente com os mesmos argumentos não terá efeito adicional no ambiente. (Padrão: falso).
  • openWorldHint: se for verdadeiro, a ferramenta poderá interagir com um "mundo aberto" de entidades externas. Se for falso, a ferramenta só poderá interagir com entidades internas. Por exemplo, uma ferramenta de pesquisa na Web seria de mundo aberto, enquanto uma ferramenta de memória não seria.

Dica destrutiva: ❌ | Dica idempotente: ✅ | Dica somente leitura: ✅ | Dica de mundo aberto: ❌

Escopos de autorização

Requer um dos seguintes escopos do OAuth:

  • https://www.googleapis.com/auth/classroom.courses.readonly
  • https://www.googleapis.com/auth/classroom.rosters.readonly