Using the MCP server

Hireway runs a Model Context Protocol (MCP) server, so AI clients such as Claude, Cursor and Codex can read and edit your resumes, cover letters and job applications when you ask them to in plain language. This guide shows you how to connect a client and lists everything the server offers.

Before you startCopy Anchor Link

• You need a Hireway account.
• Your MCP client must support remote servers over Streamable HTTP, or be able to run the mcp-remote bridge.
• Decide how the client signs in:
  • OAuth (recommended). You approve the client in your browser. No secret is copied anywhere.
  • API key. For clients that can't do OAuth but can send a custom header. Create a key first, as described in Using the API.

Find your server addressCopy Anchor Link

The server address is https://hireway.dev/mcp. You can copy it from Settings → AI & developer, in the MCP server section.

Connect with OAuthCopy Anchor Link

Add the server to your client

Add a remote MCP server with the address https://hireway.dev/mcp and no headers. Client-specific steps are in Set up popular clients.

Sign in to Hireway

Your client opens a browser window. If you aren't signed in, Hireway asks you to sign in first.

Approve the connection

Check the application name under Connect an application, read what it will be able to do, and select Allow access. Select Deny if you don't recognize the application.

Return to your client

The browser hands control back to your client, which can now use the Hireway tools.

Connect with an API keyCopy Anchor Link

If your client can't do OAuth, send your API key in the x-api-key header:

{
  "mcpServers": {
    "hireway": {
      "url": "https://hireway.dev/mcp",
      "headers": { "x-api-key": "YOUR_API_KEY" }
    }
  }
}

If your client only runs local commands, use mcp-remote as a bridge. It needs a current version of Node.js:

{
  "mcpServers": {
    "hireway": {
      "command": "npx",
      "args": ["mcp-remote", "https://hireway.dev/mcp", "--header", "x-api-key:YOUR_API_KEY"]
    }
  }
}

Set up popular clientsCopy Anchor Link

claude mcp add --transport http hireway https://hireway.dev/mcp

{
  "mcpServers": {
    "hireway": { "url": "https://hireway.dev/mcp" }
  }
}

codex mcp add hireway --url https://hireway.dev/mcp
codex mcp login hireway

[mcp_servers.hireway]
url = "https://hireway.dev/mcp"
http_headers = { "x-api-key" = "YOUR_API_KEY" }

Try itCopy Anchor Link

Ask your client something like:

• "List my resumes."
• "Change the headline on my Game Developer Resume to Senior Game Developer."
• "Add Unreal Engine 5 to my skills with the level Expert."
• "Make a copy of my Game Developer Resume for a technical designer role."
• "Review my resume and give me a score." (uses the review_resume prompt)

Before it edits, the client reads the resume with read_resume, then changes it with apply_resume_patch. Every change it makes appears in the resume's history as AI edit, so you can restore an earlier version. See Undoing changes and version history.

For job applications, see Managing applications with MCP.

ToolsCopy Anchor Link

The server keeps the original 43 tool names and adds API-derived tools for the remaining workflows. Each advertises input/output schemas, structured results and MCP annotations. Clients should use these hints to decide when to request confirmation; the server independently enforces authentication, permissions and ownership. Use tools/list or the server card for the current catalog.

ResumesCopy Anchor Link

Cover lettersCopy Anchor Link

ApplicationsCopy Anchor Link

The last four tools send data to the AI provider you set up in Hireway and need a tested default provider. See Connecting an AI provider.

Additional API workflowsCopy Anchor Link

Additional tools use api_ followed by the API router path in snake case. Inputs come from the same validated contracts as the API. Existing tool names remain available.

Resume and letter exports return authenticated REST URLs. Download with your existing credentials or open in your signed-in browser. Letter localization words are encoded in the URL. No generated file is permanently copied into storage by the export tool.

Lists default to 20 results and accept limit (up to 100) and offset; continue paging until no more results. Array results use { items: [...] } in structuredContent. Scalar results use { result: ... }. Dates use ISO 8601. Resume edits can use optimistic concurrency with expectedUpdatedAt; letter edits require expectedRevision. After a conflict, reread before retrying.

Document listing never deletes expired Trash. Run api_documents_purge_expired explicitly to permanently remove documents trashed more than 30 days ago. Individual permanent deletion requires moving the document to Trash first.

File limits and referencesCopy Anchor Link

The Streamable HTTP JSON request limit is 4 MiB. Inline base64 is limited to 3 MiB of encoded text (approximately 2.25 MiB of file bytes), leaving space for JSON metadata. Larger files use an owned storagePath returned by the REST file upload or assistant attachment endpoint:

{
  "file": {
    "name": "resume.pdf",
    "contentType": "application/pdf",
    "storagePath": "uploads/YOUR_USER_ID/pictures/FILE_ID.pdf"
  }
}

The server reads storage directly and verifies the account prefix and path segments. External URLs and other users' files cannot be used as references. The API still validates each operation's file type and size: ordinary uploads/imports and application PDFs allow 10 MiB, PDF checking allows 25,000,000 bytes, and assistant attachments allow 25 MiB. Upload larger assistant attachments through their REST endpoint before referencing them. Small application attachments use fileName, contentType, and either dataBase64 or storagePath.

Browser and streaming workflowsCopy Anchor Link

open_account_settings opens profile, security, API keys, preferences or account settings. Provider creation/update and web credential entry return their authenticated settings page. Account deletion, password changes, passkeys, two-factor authentication and provider credentials require user interaction in that browser. Browser preferences, local undo and document selection remain browser workflows; durable edits and history are available through MCP.

MCP is stateless and accepts POST requests with JSON responses. GET/DELETE return 405; there is no standalone SSE subscription. Draft/message streams are collected up to 500,000 characters; truncated identifies longer responses. Read the assistant thread for persisted replies. api_resume_updates_subscribe returns an owned snapshot; poll its updatedAt for changes. api_resume_verify_password returns a resource cookie capability; pass it as resourceCookie to api_resume_get_by_slug. It expires server-side after ten minutes and cannot authenticate an account.

The installed SDK uses its supported MCP 1.x protocol negotiation, including 2025-11-25. Protocol revisions beyond that require a separate SDK/compatibility upgrade; this server does not claim support for untested future versions.

Browser requests must use the configured application Origin; native clients normally omit Origin. Responses are private and uncached. Request/user rate limits supplement each API operation's own limits; signed PDF downloads share the renderer limit with REST exports.

PromptsCopy Anchor Link

Prompts are ready-made instructions your client can start from. Each takes a resume id and includes that resume and the schema.

ResourcesCopy Anchor Link

Hireway also publishes a server card at /.well-known/mcp/server-card.json that summarizes the tools, prompts and resources, for clients that discover servers without connecting.

How authentication worksCopy Anchor Link

This section is for client developers.

• The server checks x-api-key: <key> first, then Authorization: Bearer <token>. MCP never accepts account session cookies. Invalid explicit credentials cannot borrow a browser session.
• A request with neither gets 401 and a WWW-Authenticate: Bearer resource_metadata="https://hireway.dev/.well-known/oauth-protected-resource" header. OAuth clients use it to discover the authorization server.
• Authorization server metadata is at /.well-known/oauth-authorization-server. The authorization server supports dynamic client registration and PKCE with S256.
• New OAuth clients can request api:read, api:write and api:delete. The consent screen describes these permissions alongside identity scopes. Existing identity-only grants and legacy keys without permission statements retain account-wide access for compatibility.
• The server checks the user, client, login session and consent grant on every authenticated request. Disabled clients, banned accounts, ended sessions and revoked grants cannot continue using signed tokens. Proof-bound DPoP tokens are rejected: this endpoint supports ordinary bearer access tokens.
• Revoke a connection under Settings → AI & developer → Connected applications. Revoking the application grant invalidates existing access and refresh tokens. The authorization provider does not support revoking one self-contained JWT independently of its grant.

TroubleshootingCopy Anchor Link

Related guidesCopy Anchor Link

• Managing applications with MCP: prompts for tracking your job search from an AI client.
• Using the patch API: how resume edits are expressed.
• Using the API: API keys and the REST API.