Connect Badal to ChatGPT, Codex, or Claude Code

The setup depends on where your agent runs. ChatGPT Web needs a supported remote MCP connection and browser authorization. Local Codex and Claude Code can use Badal's downloadable Recruiter skill, which includes a private command-line helper. A prompt or skill alone can teach the workflow, but it does not give the agent account access. Always verify the connected account before creating a role or inspecting candidates.

This guide is for recruiters who want to work in conversation: describe the job, answer focused questions, approve the role, and get the real application link back. It does not require candidates to use an agent. They see a public form that asks one question at a time. Badal handles the screening and assessment workflow after submission, subject to the account's available AI screening capacity.

First, choose the environment you actually use

Do not try to authorize a local client by opening its 127.0.0.1 callback inside a different browser environment. That address belongs to the client that initiated the flow. The MCP authorization specification explains the client/server roles; Badal's agent docs contain the current product instructions.

Set up ChatGPT Web through MCP

In a ChatGPT workspace that supports custom MCP connections, add Badal's server URL from within ChatGPT's connection interface. When ChatGPT asks for access, sign in to your Badal recruiter account in the browser and approve the requested connection. Return to the chat and ask the agent to identify the account it can see. If the account tool does not succeed, the connection is not ready, even if the approval page looked successful.

Use a fresh connection attempt after an expired or previously used authorization page. Do not paste a manual API key into the conversation merely because a plugin fails; that does not install private HTTP tools. ChatGPT workspace policies and available connection features may vary, so check the current Badal docs and your ChatGPT connection UI.

As a first read-only task, ask: “Which Badal recruiter account is connected, and how many open job posts do I have?” A correct answer should come from the account and campaigns tools. It should not be inferred from a screenshot or a prior chat. Only then move to creating a new role.

Set up local Codex or Claude Code through the skill

Download the Badal Recruiter ZIP, inspect it, and install the badal-recruiter folder in the skill directory for your local agent. Codex normally uses ~/.agents/skills/badal-recruiter; Claude Code uses ~/.claude/skills/badal-recruiter. Refresh skill discovery or restart the local agent if it does not appear. Read the connection reference for the exact current steps.

You have two credential choices. A one-time connection link is created in Badal → Agent access, can be redeemed once, and gives temporary access for 24 hours after redemption. In a trusted local agent conversation, you may paste that link so the agent can feed it to the helper's stdin without showing it in a command or output. The link remains in the chat history, so use the hidden terminal prompt if you prefer less exposure. The agent should not echo, browse to, or log the link.

For access that persists until you revoke it, create a Manual API key in Agent access and run:

python3 ~/.agents/skills/badal-recruiter/scripts/badal.py connect-key

Paste the key at the helper's hidden prompt. Do not put a long-lived key in an agent chat, shell argument, public role, or candidate email. The helper verifies the key against Badal before saving it to a private credential file. Use a separate named key for each device or agent environment so you can revoke one without interrupting the rest.

Verify before taking action

With the local helper, run:

python3 ~/.agents/skills/badal-recruiter/scripts/badal.py status
python3 ~/.agents/skills/badal-recruiter/scripts/badal.py request GET /api/me

status tells you whether a local credential exists and whether a temporary one has expired. The /api/me request confirms server access and the recruiter identity. A saved file from another machine does not appear automatically in a cloud runtime. If the helper reports no credential, connect in the same environment where the agent will work. If it reports a revoked or expired credential, create a fresh link or key; do not copy a private credential file into chat.

For ChatGPT Web, ask the agent to call its account tool. A direct HTTP X-Admin-Key header is for authorized HTTP clients; a local skill should keep the key inside its helper. A custom MCP client may instead use a privately configured bearer credential, where the client supports it. See Badal's agent map for the exact current boundaries.

Give the agent a first real task

Once access is verified, ask for a draft, not an immediate publish:

Help me create a [role] at [organization] in Badal. Ask one question at a time for the candidate-facing recruiter name, actual work, location, evidence to collect, screening criteria, and a short practical assignment. Show me the complete draft before publishing. When I approve, create the job post and show the returned public application link. After that, report candidate stage counts and job failures separately. Ask before final keep or reject decisions.

This prompt gives the agent a job it can finish and a point where you can catch mistakes. For the form itself, the application guide includes evidence questions; for the whole operating model, read agent-operated hiring with MCP.

Troubleshooting in order

1. No skill found: confirm the installed folder contains SKILL.md and restart skill discovery. A skill installed on a laptop is not installed on a separate cloud agent.
2. No credential saved: connect from the environment that will make Badal requests. A pasted instruction file cannot transfer a private key.
3. Connection page expired: begin a new authorization flow. Do not submit an old approval page repeatedly.
4. Account check fails: stop role creation, confirm the signed-in Badal account, and reconnect.
5. Tool unavailable: confirm the client actually supports MCP or the local helper. Plain web browsing is not authenticated API access.

Agent-ready connection check

State which Badal environment you are running in. Read /llms.txt and /docs. Use the connection method supported by this environment. Verify the account with the account tool or /api/me, then list open roles. If verification fails, describe the exact missing capability without claiming account access. Never ask me to place a manual key in chat.

Frequently asked questions

Can I paste the one-time link into Codex chat?

Yes, in a trusted local Codex session with the skill helper. The agent should redeem it immediately through private stdin. The link remains in that conversation history, even though it can only be used once. The hidden prompt remains the more private choice.

Will a manual key expire after 24 hours?

No. A manual key stays valid until you revoke it in Agent access. The 24-hour limit belongs to the temporary connection flow. Name manual keys clearly and revoke one when a device, agent environment, or team member no longer needs access.