MBTA V3 API

naftiko: 1.0.0-alpha2
info:
  label: MBTA V3 API
  description: The MBTA V3 API provides fast, easy access to Massachusetts Bay Transportation Authority schedules, alerts,
    and real-time information. Returns JSON:API formatted responses (application/vnd.api+json) for routes, stops, trips, schedules,
    predictions, vehicles, alerts, lines, facilities, services, shapes, and route patterns. Free API keys are available via
    the developer portal for higher rate limits.
  tags:
  - Mbta
  - API
  created: '2026-05-06'
  modified: '2026-05-06'
capability:
  consumes:
  - type: http
    namespace: mbta
    baseUri: https://api-v3.mbta.com
    description: MBTA V3 API HTTP API.
    authentication:
      type: apikey
      in: header
      name: x-api-key
      value: '{{MBTA_TOKEN}}'
    resources:
    - name: alerts
      path: /alerts
      operations:
      - name: listalerts
        method: GET
        description: List alerts
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: alerts-id
      path: /alerts/{id}
      operations:
      - name: getalert
        method: GET
        description: Get alert
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: facilities
      path: /facilities
      operations:
      - name: listfacilities
        method: GET
        description: List facilities
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: facilities-id
      path: /facilities/{id}
      operations:
      - name: getfacility
        method: GET
        description: Get facility
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: lines
      path: /lines
      operations:
      - name: listlines
        method: GET
        description: List lines
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: lines-id
      path: /lines/{id}
      operations:
      - name: getline
        method: GET
        description: Get line
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: predictions
      path: /predictions
      operations:
      - name: listpredictions
        method: GET
        description: List predictions
        inputParameters:
        - name: filter[stop]
          in: query
          type: string
        - name: filter[route]
          in: query
          type: string
        - name: filter[trip]
          in: query
          type: string
        - name: filter[direction_id]
          in: query
          type: integer
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: routes
      path: /routes
      operations:
      - name: listroutes
        method: GET
        description: List routes
        inputParameters:
        - name: filter[stop]
          in: query
          type: string
        - name: filter[type]
          in: query
          type: string
        - name: filter[direction_id]
          in: query
          type: integer
        - name: filter[date]
          in: query
          type: string
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: routes-id
      path: /routes/{id}
      operations:
      - name: getroute
        method: GET
        description: Get route
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: route-patterns
      path: /route_patterns
      operations:
      - name: listroutepatterns
        method: GET
        description: List route patterns
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: route-patterns-id
      path: /route_patterns/{id}
      operations:
      - name: getroutepattern
        method: GET
        description: Get route pattern
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: schedules
      path: /schedules
      operations:
      - name: listschedules
        method: GET
        description: List schedules
        inputParameters:
        - name: filter[date]
          in: query
          type: string
        - name: filter[direction_id]
          in: query
          type: integer
        - name: filter[route]
          in: query
          type: string
        - name: filter[stop]
          in: query
          type: string
        - name: filter[trip]
          in: query
          type: string
        - name: filter[min_time]
          in: query
          type: string
        - name: filter[max_time]
          in: query
          type: string
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: services
      path: /services
      operations:
      - name: listservices
        method: GET
        description: List services
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: services-id
      path: /services/{id}
      operations:
      - name: getservice
        method: GET
        description: Get service
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: shapes
      path: /shapes
      operations:
      - name: listshapes
        method: GET
        description: List shapes
        inputParameters:
        - name: filter[route]
          in: query
          type: string
          required: true
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: shapes-id
      path: /shapes/{id}
      operations:
      - name: getshape
        method: GET
        description: Get shape
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: stops
      path: /stops
      operations:
      - name: liststops
        method: GET
        description: List stops
        inputParameters:
        - name: filter[latitude]
          in: query
          type: number
        - name: filter[longitude]
          in: query
          type: number
        - name: filter[radius]
          in: query
          type: number
        - name: filter[route]
          in: query
          type: string
        - name: filter[route_type]
          in: query
          type: string
        - name: filter[location_type]
          in: query
          type: string
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: stops-id
      path: /stops/{id}
      operations:
      - name: getstop
        method: GET
        description: Get stop
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: trips
      path: /trips
      operations:
      - name: listtrips
        method: GET
        description: List trips
        inputParameters:
        - name: filter[date]
          in: query
          type: string
        - name: filter[direction_id]
          in: query
          type: integer
        - name: filter[route]
          in: query
          type: string
        - name: filter[route_pattern]
          in: query
          type: string
        - name: filter[name]
          in: query
          type: string
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: trips-id
      path: /trips/{id}
      operations:
      - name: gettrip
        method: GET
        description: Get trip
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: vehicles
      path: /vehicles
      operations:
      - name: listvehicles
        method: GET
        description: List vehicles
        inputParameters:
        - name: filter[trip]
          in: query
          type: string
        - name: filter[label]
          in: query
          type: string
        - name: filter[route]
          in: query
          type: string
        - name: filter[direction_id]
          in: query
          type: integer
        - name: filter[route_type]
          in: query
          type: string
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: vehicles-id
      path: /vehicles/{id}
      operations:
      - name: getvehicle
        method: GET
        description: Get vehicle
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  exposes:
  - type: rest
    port: 8080
    namespace: mbta-rest
    description: REST adapter for MBTA V3 API.
    resources:
    - path: /alerts
      name: listalerts
      operations:
      - method: GET
        name: listalerts
        description: List alerts
        call: mbta.listalerts
        outputParameters:
        - type: object
          mapping: $.
    - path: /alerts/{id}
      name: getalert
      operations:
      - method: GET
        name: getalert
        description: Get alert
        call: mbta.getalert
        outputParameters:
        - type: object
          mapping: $.
    - path: /facilities
      name: listfacilities
      operations:
      - method: GET
        name: listfacilities
        description: List facilities
        call: mbta.listfacilities
        outputParameters:
        - type: object
          mapping: $.
    - path: /facilities/{id}
      name: getfacility
      operations:
      - method: GET
        name: getfacility
        description: Get facility
        call: mbta.getfacility
        outputParameters:
        - type: object
          mapping: $.
    - path: /lines
      name: listlines
      operations:
      - method: GET
        name: listlines
        description: List lines
        call: mbta.listlines
        outputParameters:
        - type: object
          mapping: $.
    - path: /lines/{id}
      name: getline
      operations:
      - method: GET
        name: getline
        description: Get line
        call: mbta.getline
        outputParameters:
        - type: object
          mapping: $.
    - path: /predictions
      name: listpredictions
      operations:
      - method: GET
        name: listpredictions
        description: List predictions
        call: mbta.listpredictions
        outputParameters:
        - type: object
          mapping: $.
    - path: /routes
      name: listroutes
      operations:
      - method: GET
        name: listroutes
        description: List routes
        call: mbta.listroutes
        outputParameters:
        - type: object
          mapping: $.
    - path: /routes/{id}
      name: getroute
      operations:
      - method: GET
        name: getroute
        description: Get route
        call: mbta.getroute
        outputParameters:
        - type: object
          mapping: $.
    - path: /route_patterns
      name: listroutepatterns
      operations:
      - method: GET
        name: listroutepatterns
        description: List route patterns
        call: mbta.listroutepatterns
        outputParameters:
        - type: object
          mapping: $.
    - path: /route_patterns/{id}
      name: getroutepattern
      operations:
      - method: GET
        name: getroutepattern
        description: Get route pattern
        call: mbta.getroutepattern
        outputParameters:
        - type: object
          mapping: $.
    - path: /schedules
      name: listschedules
      operations:
      - method: GET
        name: listschedules
        description: List schedules
        call: mbta.listschedules
        outputParameters:
        - type: object
          mapping: $.
    - path: /services
      name: listservices
      operations:
      - method: GET
        name: listservices
        description: List services
        call: mbta.listservices
        outputParameters:
        - type: object
          mapping: $.
    - path: /services/{id}
      name: getservice
      operations:
      - method: GET
        name: getservice
        description: Get service
        call: mbta.getservice
        outputParameters:
        - type: object
          mapping: $.
    - path: /shapes
      name: listshapes
      operations:
      - method: GET
        name: listshapes
        description: List shapes
        call: mbta.listshapes
        outputParameters:
        - type: object
          mapping: $.
    - path: /shapes/{id}
      name: getshape
      operations:
      - method: GET
        name: getshape
        description: Get shape
        call: mbta.getshape
        outputParameters:
        - type: object
          mapping: $.
    - path: /stops
      name: liststops
      operations:
      - method: GET
        name: liststops
        description: List stops
        call: mbta.liststops
        outputParameters:
        - type: object
          mapping: $.
    - path: /stops/{id}
      name: getstop
      operations:
      - method: GET
        name: getstop
        description: Get stop
        call: mbta.getstop
        outputParameters:
        - type: object
          mapping: $.
    - path: /trips
      name: listtrips
      operations:
      - method: GET
        name: listtrips
        description: List trips
        call: mbta.listtrips
        outputParameters:
        - type: object
          mapping: $.
    - path: /trips/{id}
      name: gettrip
      operations:
      - method: GET
        name: gettrip
        description: Get trip
        call: mbta.gettrip
        outputParameters:
        - type: object
          mapping: $.
    - path: /vehicles
      name: listvehicles
      operations:
      - method: GET
        name: listvehicles
        description: List vehicles
        call: mbta.listvehicles
        outputParameters:
        - type: object
          mapping: $.
    - path: /vehicles/{id}
      name: getvehicle
      operations:
      - method: GET
        name: getvehicle
        description: Get vehicle
        call: mbta.getvehicle
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    port: 9090
    namespace: mbta-mcp
    transport: http
    description: MCP adapter for MBTA V3 API for AI agent use.
    tools:
    - name: listalerts
      description: List alerts
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: mbta.listalerts
      outputParameters:
      - type: object
        mapping: $.
    - name: getalert
      description: Get alert
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: mbta.getalert
      outputParameters:
      - type: object
        mapping: $.
    - name: listfacilities
      description: List facilities
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: mbta.listfacilities
      outputParameters:
      - type: object
        mapping: $.
    - name: getfacility
      description: Get facility
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: mbta.getfacility
      outputParameters:
      - type: object
        mapping: $.
    - name: listlines
      description: List lines
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: mbta.listlines
      outputParameters:
      - type: object
        mapping: $.
    - name: getline
      description: Get line
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: mbta.getline
      outputParameters:
      - type: object
        mapping: $.
    - name: listpredictions
      description: List predictions
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: mbta.listpredictions
      with:
        filter[stop]: tools.filter[stop]
        filter[route]: tools.filter[route]
        filter[trip]: tools.filter[trip]
        filter[direction_id]: tools.filter[direction_id]
      inputParameters:
      - name: filter[stop]
        type: string
        description: filter[stop]
      - name: filter[route]
        type: string
        description: filter[route]
      - name: filter[trip]
        type: string
        description: filter[trip]
      - name: filter[direction_id]
        type: integer
        description: filter[direction_id]
      outputParameters:
      - type: object
        mapping: $.
    - name: listroutes
      description: List routes
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: mbta.listroutes
      with:
        filter[stop]: tools.filter[stop]
        filter[type]: tools.filter[type]
        filter[direction_id]: tools.filter[direction_id]
        filter[date]: tools.filter[date]
      inputParameters:
      - name: filter[stop]
        type: string
        description: filter[stop]
      - name: filter[type]
        type: string
        description: filter[type]
      - name: filter[direction_id]
        type: integer
        description: filter[direction_id]
      - name: filter[date]
        type: string
        description: filter[date]
      outputParameters:
      - type: object
        mapping: $.
    - name: getroute
      description: Get route
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: mbta.getroute
      outputParameters:
      - type: object
        mapping: $.
    - name: listroutepatterns
      description: List route patterns
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: mbta.listroutepatterns
      outputParameters:
      - type: object
        mapping: $.
    - name: getroutepattern
      description: Get route pattern
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: mbta.getroutepattern
      outputParameters:
      - type: object
        mapping: $.
    - name: listschedules
      description: List schedules
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: mbta.listschedules
      with:
        filter[date]: tools.filter[date]
        filter[direction_id]: tools.filter[direction_id]
        filter[route]: tools.filter[route]
        filter[stop]: tools.filter[stop]
        filter[trip]: tools.filter[trip]
        filter[min_time]: tools.filter[min_time]
        filter[max_time]: tools.filter[max_time]
      inputParameters:
      - name: filter[date]
        type: string
        description: filter[date]
      - name: filter[direction_id]
        type: integer
        description: filter[direction_id]
      - name: filter[route]
        type: string
        description: filter[route]
      - name: filter[stop]
        type: string
        description: filter[stop]
      - name: filter[trip]
        type: string
        description: filter[trip]
      - name: filter[min_time]
        type: string
        description: filter[min_time]
      - name: filter[max_time]
        type: string
        description: filter[max_time]
      outputParameters:
      - type: object
        mapping: $.
    - name: listservices
      description: List services
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: mbta.listservices
      outputParameters:
      - type: object
        mapping: $.
    - name: getservice
      description: Get service
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: mbta.getservice
      outputParameters:
      - type: object
        mapping: $.
    - name: listshapes
      description: List shapes
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: mbta.listshapes
      with:
        filter[route]: tools.filter[route]
      inputParameters:
      - name: filter[route]
        type: string
        description: filter[route]
        required: true
      outputParameters:
      - type: object
        mapping: $.
    - name: getshape
      description: Get shape
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: mbta.getshape
      outputParameters:
      - type: object
        mapping: $.
    - name: liststops
      description: List stops
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: mbta.liststops
      with:
        filter[latitude]: tools.filter[latitude]
        filter[longitude]: tools.filter[longitude]
        filter[radius]: tools.filter[radius]
        filter[route]: tools.filter[route]
        filter[route_type]: tools.filter[route_type]
        filter[location_type]: tools.filter[location_type]
      inputParameters:
      - name: filter[latitude]
        type: number
        description: filter[latitude]
      - name: filter[longitude]
        type: number
        description: filter[longitude]
      - name: filter[radius]
        type: number
        description: filter[radius]
      - name: filter[route]
        type: string
        description: filter[route]
      - name: filter[route_type]
        type: string
        description: filter[route_type]
      - name: filter[location_type]
        type: string
        description: filter[location_type]
      outputParameters:
      - type: object
        mapping: $.
    - name: getstop
      description: Get stop
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: mbta.getstop
      outputParameters:
      - type: object
        mapping: $.
    - name: listtrips
      description: List trips
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: mbta.listtrips
      with:
        filter[date]: tools.filter[date]
        filter[direction_id]: tools.filter[direction_id]
        filter[route]: tools.filter[route]
        filter[route_pattern]: tools.filter[route_pattern]
        filter[name]: tools.filter[name]
      inputParameters:
      - name: filter[date]
        type: string
        description: filter[date]
      - name: filter[direction_id]
        type: integer
        description: filter[direction_id]
      - name: filter[route]
        type: string
        description: filter[route]
      - name: filter[route_pattern]
        type: string
        description: filter[route_pattern]
      - name: filter[name]
        type: string
        description: filter[name]
      outputParameters:
      - type: object
        mapping: $.
    - name: gettrip
      description: Get trip
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: mbta.gettrip
      outputParameters:
      - type: object
        mapping: $.
    - name: listvehicles
      description: List vehicles
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: mbta.listvehicles
      with:
        filter[trip]: tools.filter[trip]
        filter[label]: tools.filter[label]
        filter[route]: tools.filter[route]
        filter[direction_id]: tools.filter[direction_id]
        filter[route_type]: tools.filter[route_type]
      inputParameters:
      - name: filter[trip]
        type: string
        description: filter[trip]
      - name: filter[label]
        type: string
        description: filter[label]
      - name: filter[route]
        type: string
        description: filter[route]
      - name: filter[direction_id]
        type: integer
        description: filter[direction_id]
      - name: filter[route_type]
        type: string
        description: filter[route_type]
      outputParameters:
      - type: object
        mapping: $.
    - name: getvehicle
      description: Get vehicle
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: mbta.getvehicle
      outputParameters:
      - type: object
        mapping: $.
binds:
- namespace: env
  keys:
    MBTA_TOKEN: MBTA_TOKEN