Skip to content
AxecAxec Docs

Quickstart

This quickstart runs one small script that lists the open issues in a GitHub repository for you. The script signs you in to Axec, asks for your approval, and calls GitHub through Axec, so your code never sees a GitHub token. It takes about ten minutes once you have created your agent in the console.

Before you start

Section titled “Before you start”

You need Node.js 22.5 or newer and a GitHub account that can read at least one repository. You also need an Axec account. Axec is in early access, so request access first and we will set up your account.

Then sign in to the Axec Console and set up your agent in three steps:

  1. Provision the GitHub connector. Add GitHub to your account by following the GitHub connector guide. Axec gives it an MCP URL such as https://axec.dev/ws/acme/connectors/github, and the script only needs the key at the end, github.
  2. Create an Application and link the connector. The Application is your agent’s identity in Axec. See Connect an upstream provider.
  3. Create application credentials. The script signs in with OAuth and PKCE, so create a public credential and add http://127.0.0.1:3000/callback as an allowed redirect address.

Before you leave the console, note down your workspace URL, such as https://axec.dev/ws/acme, and the client ID of the credential you just created. The script below needs both, along with the connector key github.

1. Install the SDK

Section titled “1. Install the SDK”
Terminal window
pnpm add @axec/sdk
pnpm add -D tsx

2. Sign in and approve access

Section titled “2. Sign in and approve access”

Save the following as issues.mts. It creates an SDK client for the GitHub connector, prints a sign-in link, and waits for the browser to return to a small local server that listens on port 3000.

import { createServer } from "node:http";
import { setupPublicClient } from "@axec/sdk/client";


const setup = await setupPublicClient({
  workspaceUrl: "https://axec.dev/ws/acme",
  target: { mode: "mediated", connectorKey: "github" },
  clientId: process.env.AXEC_CLIENT_ID!,
  redirectUri: "http://127.0.0.1:3000/callback",
  scopes: ["mcp:invoke"],
});


const callbackUrl = new Promise<string>((resolve) => {
  const server = createServer((request, response) => {
    if (!request.url?.startsWith("/callback")) {
      response.statusCode = 404;
      return response.end();
    }
    response.end("Signed in. You can close this tab.");
    server.close();
    resolve(`http://127.0.0.1:3000${request.url}`);
  }).listen(3000, "127.0.0.1");
});


await setup.startAuthorization((url) =>
  console.log(`Open this link to sign in:\n${url}`),
);
await setup.auth.completeCallback(await callbackUrl, {
  resource: setup.resource,
});

Run it with your client ID, then open the link it prints:

Terminal window
export AXEC_CLIENT_ID="<your client ID>"
npx tsx issues.mts

In the browser, sign in with your company login, connect your GitHub account if you have not already, review what the agent is asking to do, and approve it. Axec then sends the browser back to your local server, and the SDK exchanges the result for an access token that works only for this connector.

3. List the tools and call one

Section titled “3. List the tools and call one”

Add the next lines to the end of issues.mts. The first request asks Axec which tools you are allowed to use, and the second calls the one that lists issues. Replace acme and web with a repository you can read.

const listed = await setup.mcp.request<{
  result: { tools: { name: string }[] };
}>({
  jsonrpc: "2.0",
  id: 1,
  method: "tools/list",
  params: {},
});
console.log(listed.result.tools.map((tool) => tool.name));


const tool = listed.result.tools.find((candidate) =>
  candidate.name.endsWith("list_issues"),
);
if (!tool) throw new Error("No issue-listing tool is available to you");


const issues = await setup.mcp.request({
  jsonrpc: "2.0",
  id: 2,
  method: "tools/call",
  params: {
    name: tool.name,
    arguments: { owner: "acme", repo: "web", state: "OPEN", perPage: 5 },
  },
});
console.log(JSON.stringify(issues, null, 2));

Run the script again. Axec remembers that you connected GitHub, but the access token lives only in memory, so you sign in again each time. The script prints the tool names the GitHub connector exposes to you, followed by up to five open issues from the repository. Your issue-listing tool is probably named list_issues.

4. See the record in the console

Section titled “4. See the record in the console”

Open the Axec Console, choose Applications, select your agent, and open Tool calls. You should see the call you just made as allowed, with your name as the person it acted for, the GitHub connector, and the tool that ran. If you revoke your approval from the console and run the script again, the call fails, because Axec checks your current access on every request instead of trusting the earlier sign-in.

What just happened

Section titled “What just happened”

The SDK discovered your workspace’s sign-in endpoints, ran the OAuth sign-in with PKCE, and kept the resulting access token for the GitHub connector only. When your script called the tool, Axec checked your approval and policy, used the GitHub account you connected to make the request, and returned only the result. Your script never held a GitHub token, and the call was recorded against you and your agent.

Troubleshooting

Section titled “Troubleshooting”
Symptom What to check
The sign-in page rejects the link The client ID is correct, and the public credentials list exactly http://127.0.0.1:3000/callback as an allowed redirect.
No GitHub tools are listed The GitHub connector is linked to your Application, and you approved GitHub access during sign-in.
The call says approval is needed A policy requires a person to approve this action. Approve it in the console and run the script again.
Port 3000 is already in use Stop the other process, or add a different redirect address to your public credentials and change redirectUri and listen to match.

Next steps

Section titled “Next steps”