MCP Tools Reference: classroommcp.googleapis.com

Herramienta: list_courses

Muestra una lista de los cursos del usuario con sus detalles (sección, sala, asignatura, niveles de grado, descripción, objetivos de aprendizaje, estado y rol del usuario). Usa este método como el punto de entrada principal para descubrir cursos y recuperar sus IDs. Los cursos suelen compartir un título, por lo que debes usar la sección para distinguirlos. Solo devuelve cursos ACTIVOS, a menos que se establezca courseState (p.ej., ARCHIVADO).

Para vincular al usuario a un curso en la app web de Classroom, usa https://classroom.google.com/c/{course_id} (Novedades) o https://classroom.google.com/w/{course_id}/t/all (página Trabajo en clase). Usa los IDs exactamente como se devuelven; nunca los adivines ni los modifiques.

En la siguiente muestra de código, se indica cómo usar curl para llamar a la herramienta de MCP list_courses.

Solicitud de 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

Solicitud para enumerar cursos.

ListCoursesRequest

Representación JSON
{
  "courseState": enum (State),
  "createdDateRange": {
    object (DateRange)
  },
  "timeZone": string,
  "titleContains": string,
  "pageSize": integer,
  "pageToken": string
}
Campos
courseState

enum (State)

Opcional. Filtra por estado del curso. La configuración predeterminada es ACTIVE.

createdDateRange

object (DateRange)

Opcional. Filtrar por rango de fechas de creación

timeZone

string

Obligatorio. Es la zona horaria de la IANA del usuario (p.ej., "America/Los_Angeles"). Las fechas de esta solicitud se interpretan en ella y las fechas de la respuesta se formatean en ella, lo que coincide con lo que el usuario ve en Classroom.

titleContains

string

Opcional. Filtra el título por substring que no distingue mayúsculas de minúsculas.

pageSize

integer

Opcional. Controla el tamaño de la página. La configuración predeterminada es 10; el máximo es 50.

pageToken

string

Opcional. Es el token para la paginación.

DateRange

Representación JSON
{
  "startDate": string,
  "endDate": string
}
Campos
startDate

string

Es el inicio inclusivo del rango (formato: AAAA-MM-DD).

endDate

string

Fin inclusivo del rango (formato: AAAA-MM-DD).

Estado

Son los estados de un curso.

Enums
STATE_UNSPECIFIED Estado sin especificar.
ACTIVE Estado activo.
ARCHIVED Estado archivado.
PROVISIONED Estado de aprovisionamiento.

Esquema de salida

Es la respuesta para mostrar los cursos.

ListCoursesResponse

Representación JSON
{
  "courses": [
    {
      object (Course)
    }
  ],
  "nextPageToken": string
}
Campos
courses[]

object (Course)

Es la lista de cursos.

nextPageToken

string

Es el token de la página siguiente.

Curso

Representación 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

Es el identificador. Es el identificador de este curso.

title

string

Es el título del curso.

role

enum (Role)

Es el rol del usuario en este curso.

creationDate

string

Es la fecha de creación del curso (formato: AAAA-MM-DD). Está vacío si no se conoce la fecha de creación.

state

enum (State)

Solo salida. Es el estado del curso.

section

string

Opcional. Sección del curso.

room

string

Opcional. Es la sala del curso.

subject

string

Opcional. Es el tema del curso.

gradeLevels

string

Opcional. Son los niveles de educación del curso.

description

string

Opcional. Es la descripción del curso.

learningGoals[]

object (LearningGoal)

Solo salida. Objetivos de aprendizaje adjuntos a este curso.

LearningGoal

Representación JSON
{
  "id": string,
  "type": enum (Type),
  "standardCode": string,
  "title": string,
  "documentTitle": string
}
Campos
id

string

Solo salida. Es el ID del objetivo de aprendizaje. Para adjuntar un estándar, usa un id de search_course_standards (no standardCode).

type

enum (Type)

Solo salida. Es el tipo de objetivo de aprendizaje.

standardCode

string

Solo salida. Código estándar (p.ej., "NY-2.NBT.4"). Solo se propaga para los estándares.

title

string

Solo salida. Es la descripción de la declaración para los estándares o el título legible por humanos para las habilidades.

documentTitle

string

Solo salida. Es el nombre del documento del plan de estudios. Solo se propaga para los estándares.

Rol

Son los roles de un usuario en un curso.

Enums
ROLE_UNSPECIFIED Indica un rol no especificado.
TEACHER Rol de profesor.
COTEACHER Rol de profesor adjunto.
STUDENT Rol de estudiante
INVITED_OR_INACTIVE Rol invitado o inactivo.

Estado

Son los estados de un curso.

Enums
STATE_UNSPECIFIED Estado sin especificar.
ACTIVE Estado activo.
ARCHIVED Estado archivado.
PROVISIONED Estado de aprovisionamiento.

Tipo

Es el tipo de objetivo de aprendizaje.

Enums
TYPE_UNSPECIFIED Tipo de objetivo de aprendizaje sin especificar.
STANDARD Un estándar de aprendizaje de un plan de estudios académico.
SKILL Es una habilidad que representa un concepto o una competencia educativa. Solo los profesores pueden agregar o quitar habilidades en Classroom.

Anotaciones de herramientas

Las anotaciones de herramientas se envían a los clientes de MCP para describir el riesgo básico de una herramienta determinada. La mayoría de los clientes tratan estas sugerencias como no confiables, pero se pueden usar para decidir cuándo se puede enviar un mensaje de confirmación a un usuario.

Junto con la cadena de título, las siguientes sugerencias booleanas se definen de la siguiente manera:

  • readOnlyHint: Si es verdadero, la herramienta no modifica su entorno. Valor predeterminado: false.
  • destructiveHint: Si es verdadero, la herramienta puede realizar acciones destructivas. Si es falso, la herramienta solo puede realizar acciones aditivas. Valor predeterminado: true.
  • idempotentHint: Si es verdadero, llamar a la herramienta de forma repetida con los mismos argumentos no tendrá ningún efecto adicional en su entorno. Valor predeterminado: false.
  • openWorldHint: Si es verdadero, la herramienta puede interactuar con un "mundo abierto" de entidades externas. Si es falso, la herramienta solo puede interactuar con entidades internas. Por ejemplo, una herramienta de búsqueda web sería de mundo abierto, mientras que una herramienta de memoria no lo sería.

Sugerencia destructiva: ❌ | Sugerencia idempotente: ✅ | Sugerencia de solo lectura: ✅ | Sugerencia de mundo abierto: ❌

Alcances de la autorización

Se necesita uno de los siguientes alcances de OAuth:

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