PDF.co MCP Server

Instructions

Check the status and results of a job
Status can be:
- working: background job is currently in work or does not exist.
- success: background job was successfully finished.
- failed: background job failed for some reason (see message for more details).
- aborted: background job was aborted.
- unknown: unknown background job id. Available only when force is set to true for input request.

Implementation Reference

• pdfco/mcp/tools/apis/job.py:37-54 (handler)

  The main handler for the 'get_job_check' MCP tool. Includes the @mcp.tool() decorator for registration, input schema via Pydantic Field annotations, docstring, and delegates execution to the internal _get_job_status helper.

  @mcp.tool()
  async def get_job_check(
      job_id: str = Field(description="The ID of the job to get the status of"),
      api_key: str = Field(
          description="PDF.co API key. If not provided, will use X_API_KEY environment variable. (Optional)",
          default="",
      ),
  ) -> BaseResponse:
      """
      Check the status and results of a job
      Status can be:
      - working: background job is currently in work or does not exist.
      - success: background job was successfully finished.
      - failed: background job failed for some reason (see message for more details).
      - aborted: background job was aborted.
      - unknown: unknown background job id. Available only when force is set to true for input request.
      """
      return await _get_job_status(job_id, api_key)

• pdfco/mcp/models.py:5-10 (schema)

  Pydantic BaseModel defining the output schema for the get_job_check tool response.

  class BaseResponse(BaseModel):
      status: str
      content: Any
      credits_used: int | None = None
      credits_remaining: int | None = None
      tips: str | None = None

• pdfco/mcp/tools/apis/job.py:10-34 (helper)

  Internal helper function containing the core logic: makes HTTP POST to PDF.co /v1/job/check API and constructs the BaseResponse.

  async def _get_job_status(job_id: str, api_key: str = "") -> BaseResponse:
      """
      Internal helper function to check job status without MCP tool decoration
      """
      try:
          async with PDFCoClient(api_key=api_key) as client:
              response = await client.post(
                  "/v1/job/check",
                  json={
                      "jobId": job_id,
                  },
              )
              json_data = response.json()
              return BaseResponse(
                  status=json_data["status"],
                  content=json_data,
                  credits_used=json_data.get("credits"),
                  credits_remaining=json_data.get("remainingCredits"),
                  tips="You can download the result if status is success",
              )
      except Exception as e:
          return BaseResponse(
              status="error",
              content=str(e),
          )