ZillaSales in your assistant

A working Node.js quickstart

Use a current Node.js LTS release. In an empty project, install the MCP SDK and save the following as quickstart.mjs. This example makes public read-only calls; it creates no accounts, favorites or applications.

npm init -y
npm install @modelcontextprotocol/sdk@1.30.0
node quickstart.mjs

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from
  "@modelcontextprotocol/sdk/client/streamableHttp.js";

const client = new Client({ name: "my-zillasales-integration", version: "1.0.0" });

async function call(name, args = {}) {
  const result = await client.callTool({ name, arguments: args });
  if (result.isError) {
    // Preserve result._meta for your host's OAuth linking handler.
    const message = result.content
      .filter(item => item.type === "text")
      .map(item => item.text).join("\n");
    throw Object.assign(new Error(message), { mcpResult: result });
  }
  return result.structuredContent;
}

try {
  await client.connect(new StreamableHTTPClientTransport(
    new URL("https://zillasales.com/api/mcp")
  ));
  const { tools } = await client.listTools();
  console.log("Available tools:", tools.map(tool => tool.name));
  const catalog = await call("get_catalog_options");
  console.log("Working countries:", catalog.workingCountries);

  const filters = { query: "software", take: 6 };
  const first = await call("search_opportunities", filters);
  console.log("Matching opportunities:", first.total);
  for (const item of first.opportunities) {
    console.log(item.title, item.opportunityUrl, item.availableActions);
  }
  if (first.nextCursor) {
    const next = await call("search_opportunities", {
      ...filters, cursor: first.nextCursor,
    });
    console.log("Next page:", next.opportunities.length);
  }
  if (first.opportunities.length) {
    const detail = await call("get_opportunity", {
      opportunityId: first.opportunities[0].opportunityId,
    });
    console.log("Missing facts:", detail.missingInformation);
  }
} finally {
  await client.close();
}

The SDK handles initialization and the Streamable HTTP headers. Successful calls return structuredContent and an equivalent JSON text result. Check isError before reading success fields. The live inventory changes, so a valid search can return zero results.

Find recurring software opportunities in Ontario

Pass this argument object to search_opportunities. Leave applicationsAvailable unset to include SEO-only listings; set it to true when the user wants to apply.

{
  "query": "software",
  "countries": [
    "CA"
  ],
  "territories": [
    "ON"
  ],
  "commissionRecurrence": "RECURRING",
  "take": 6
}

Find and inspect sales representatives

Run these calls inside the quickstart’s try block. Rep search accepts a business query, territories, take and offset. Put products, buyer types and channels in the query; it does not accept the opportunity search’s country or commission filters.

// Use the connected client and call helper from the quickstart.
const repFilters = {
  "query": "commercial lighting for electrical wholesalers",
  "territories": [
    "TX"
  ],
  "take": 6,
  "offset": 0
};
const page = await call("search_reps", repFilters);
for (const candidate of page.profiles) {
  console.log(candidate.whyFit, candidate.interest);
}
if (page.profiles.length) {
  const candidateRef = page.profiles[0].candidateRef;
  const detail = await call("get_rep_profile", { candidateRef });
  console.log(detail.profile);
}
if (page.nextOffset !== null) {
  const next = await call("search_reps", {
    ...repFilters, offset: page.nextOffset,
  });
  console.log("Next page:", next.profiles.length);
}

Candidate references expire after 24 hours. References issued to a connected account stay bound to that account; public references can be used after connecting. Fetch the profile again before acting because eligibility and contact permissions can change. Match evidence describes possible fit, not confirmed availability, interest or buyer relationships.

Connect an account with OAuth

MCP clients should discover the authorization server from the protected resource metadata. Register a client with the actual redirect URI, then use authorization code flow with S256 PKCE and the resource https://zillasales.com/api/mcp. Keep the verifier and tokens in your client’s secure storage. A REST API key cannot substitute for an OAuth grant.

Protected resource metadata
https://zillasales.com/.well-known/oauth-protected-resource

Authorization server metadata
https://zillasales.com/.well-known/oauth-authorization-server/api/mcp/oauth

Issuer
https://zillasales.com/api/mcp/oauth

1. Start anonymously for public browsing. When an account tool returns a linking challenge, let the host open the authorization flow.
2. The user signs in to ZillaSales with Google or an email code and approves the scopes. The assistant should never request their password or email code in chat.
3. Validate state and exchange the authorization code using the original PKCE verifier, redirect URI and resource. Use the returned bearer access token for MCP requests.
4. Refresh before the one-hour access token expires. Store the newly rotated refresh token atomically; do not reuse the old one. Reused refresh tokens revoke their grant family.
5. Reconnect after revocation or the 90-day connection expiry. Users can disconnect under Settings → Integrations.

All protected tools require account:read in addition to the feature scope below. Scopes do not override the account role, record ownership or existing contact entitlements. Request only the permissions the integration uses.

Account workflows, with an explicit review

The examples below are tool argument templates for an OAuth-connected client. Replace placeholders with values returned by previous calls. They are separate steps: display the review and wait for the user’s approval before sending a confirmation call.

Company: create a private draft and submit it for moderation

After the company supplies these facts and asks you to save them, call create_opportunity_draft. Generate a new requestId for each new draft; retain that ID and the identical payload for retries. These are illustrative facts, not recommended terms for every opportunity.

{
  "requestId": "example-lighting-draft-001",
  "title": "Independent commercial lighting sales representative",
  "description": "Sell commercial LED lighting to electrical wholesalers in Texas. Commission is 10% on one-time product sales.",
  "industries": [
    "energy"
  ],
  "territories": [
    "TX"
  ],
  "commissionMin": 10,
  "commissionMax": null,
  "commissionUnit": "PERCENT",
  "commissionRecurrence": "ONE_TIME",
  "revenueModel": "TRANSACTIONAL"
}

1. Creation returns an opportunityId and revision. The draft is private and unpublished. Commission amounts can be null; do not invent missing amounts or other claims.
2. To edit, call get_my_opportunity, then update_opportunity_draft with its opportunityId, revision and all content fields. This is a complete replacement, not a partial patch.
3. Call review_opportunity_draft with the opportunityId. Display its full opportunity and effects, and ask the company to approve submission.
4. Only after approval, call submit_opportunity_for_review with that reviewToken and confirmed: true. This sends the draft to moderation and starts normal enrichment. It does not publish it.

{
  "reviewToken": "<reviewToken returned by review_opportunity_draft>",
  "confirmed": true
}

Rep: preview an application, then confirm

1. Search with applicationsAvailable: true and let the user choose an opportunity. Use save_opportunity if they only ask to save it.
2. Call prepare_application with the chosen opportunityId. Display the returned opportunity, applicant profile, alreadyApplied and sharing effects.
3. Only after the user approves, pass its reviewToken and confirmed: true to submit_application. Submission creates an application and may notify the company under the website’s existing rules.
4. Read the result and use get_my_applications for history. Retrying does not create a second application.

{
  "opportunityId": "<opportunityId returned by search_opportunities>"
}

Review tokens last 15 minutes and bind the account, action and reviewed revisions. If the listing, draft or applicant profile changes, obtain a new review and confirmation. Never generate a review token yourself or automatically set confirmed: true merely because a token was returned.

Company: shortlist candidates and review applicants

Use search_reps → get_rep_profile → save_to_shortlist with the selected candidateRef when asked to save. Read favorites with get_saved_items. For applicants, call get_my_opportunities, then get_opportunity_applicants with your opportunityId. Contact details follow existing website access; saving neither unlocks contacts nor sends outreach.

Account lists use take and offset. Increase offset by take while hasMore is true. Recheck current records before an action instead of treating an earlier list as permanent authorization.

Errors and troubleshooting

A successful HTTP response can contain an MCP tool error. Check isError, then parse the JSON text for its error code and message. Input-schema failures can also be returned directly by the MCP SDK. Read the current tools/list schema when an argument is rejected.

{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "{\"error\":{\"code\":\"REVIEW_REQUIRED\",\"message\":\"Review this action again before confirming it.\"}}"
    }
  ]
}

At the HTTP layer: 401 means the token is invalid or expired; 403 can mean a disallowed browser Origin; 405 means the stateless endpoint received GET or DELETE instead of POST; 413 means the request exceeded 32 KB; 429 means a rate limit. Respect Retry-After and use bounded backoff. Use an MCP client instead of opening the endpoint as a webpage.

For an optional in-chat comparison, pass up to eight opportunityIds to show_opportunities or candidateRefs to show_reps. These return public comparison data and a UI resource hint. Clients without MCP Apps support can render the same structured data as text. The component cannot fetch arbitrary websites or reveal extra contacts.