Ashby MCP Server

Instructions

Implementation Reference

• src/ashby/server.py:407-434 (handler)

  The `handle_call_tool` function routes the `job_list` tool call by looking up its associated endpoint in `TOOL_ENDPOINT_MAP` and calling it via the `ashby.post` method.

  @server.call_tool()
  async def handle_call_tool(name: str, arguments: dict[str, Any]) -> list[types.TextContent]:
      """Route tool calls to the correct Ashby endpoint, passing arguments directly."""
      endpoint = TOOL_ENDPOINT_MAP.get(name)
      if not endpoint:
          return [types.TextContent(type="text", text=f"Unknown tool: {name}")]
  
      try:
          # Pass arguments straight through -- tool schemas already use Ashby's
          # camelCase param names so no translation is needed.
          response = ashby.post(endpoint, data=arguments if arguments else None)
          return [types.TextContent(type="text", text=json.dumps(response, indent=2))]
      except requests.exceptions.HTTPError as e:
          error_body = ""
          if e.response is not None:
              try:
                  error_body = e.response.text
              except Exception:
                  pass
          return [
              types.TextContent(
                  type="text",
                  text=f"Ashby API error on {endpoint}: {e}\n{error_body}",
              )
          ]
      except Exception as e:
          return [types.TextContent(type="text", text=f"Error calling {endpoint}: {e}")]

• src/ashby/server.py:72-87 (registration)

  Registration of the `job_list` tool in the `TOOLS` list, including its schema definition.

  types.Tool(
      name="job_list",
      description="List all jobs (open, closed, archived). Supports cursor pagination and status filtering.",
      inputSchema={
          "type": "object",
          "properties": {
              "status": {
                  "type": "array",
                  "items": {"type": "string", "enum": ["Draft", "Open", "Closed", "Archived"]},
                  "description": "Filter by status(es). If omitted, returns all non-Draft jobs.",
              },
              "limit": {"type": "integer", "description": "Max results per page (default/max 100)"},
              "cursor": {"type": "string", "description": "Cursor for next page of results"},
          },
      },
  ),

• src/ashby/server.py:374-399 (helper)

  `TOOL_ENDPOINT_MAP` defines the mapping between the tool name `job_list` and the Ashby API endpoint `/job.list`.

  TOOL_ENDPOINT_MAP = {
      "job_list": "/job.list",
      "job_info": "/job.info",
      "job_search": "/job.search",
      "candidate_list": "/candidate.list",
      "candidate_search": "/candidate.search",
      "candidate_info": "/candidate.info",
      "candidate_create": "/candidate.create",
      "candidate_create_note": "/candidate.createNote",
      "candidate_list_notes": "/candidate.listNotes",
      "candidate_add_tag": "/candidate.addTag",
      "candidate_tag_list": "/candidateTag.list",
      "application_list": "/application.list",
      "application_info": "/application.info",
      "application_create": "/application.create",
      "application_change_stage": "/application.change_stage",
      "interview_stage_list": "/interviewStage.list",
      "interview_plan_list": "/interviewPlan.list",
      "interview_list": "/interview.list",
      "interview_info": "/interview.info",
      "department_list": "/department.list",
      "user_list": "/user.list",
      "source_list": "/source.list",
      "archive_reason_list": "/archiveReason.list",
      "location_list": "/location.list",
  }