Skip to content
AxecAxec Docs

Quickstart

This quickstart proves the complete Axec value loop against a provisioned Axec environment. It does not cover cluster installation or identity-provider administration.

What you will verify

Section titled “What you will verify”

By the end, you will have:

  • one Application with an MCP gateway;
  • one active Connector attached to that gateway;
  • delegated or autonomous authority appropriate to the Connector credential mode;
  • one successful MCP tools/call request; and
  • one correlated policy decision and upstream outcome in the Application evidence.

Prerequisites

Section titled “Prerequisites”

Ask your Axec administrator for:

  • the Axec base URL, such as https://axec.example.com;
  • your Workspace key;
  • an Application whose gateway has at least one active Connector attachment;
  • the gateway Resource URI, such as https://axec.example.com/g/release-copilot/mcp; and
  • either a public OAuth client ID and redirect URI for delegated access, or confidential Application credentials for autonomous access.

The attached Connector must expose at least one capability. User-owned OAuth and personal-credential Connectors require delegated authorization. Autonomous Client Credentials authority can use only the Application’s own eligible vaulted or no-auth attachments.

1. Choose the authority model

Section titled “1. Choose the authority model”

For User-delegated access, start Authorization Code with S256 PKCE and request the exact gateway Resource plus mcp:invoke. The TypeScript SDK handles discovery, state, PKCE, callback redemption, and Resource-scoped token storage:

import { AxecAuthClient, MemoryStorage } from "@axec/sdk";


const resource = "https://axec.example.com/g/release-copilot/mcp";
const auth = new AxecAuthClient({
  baseUrl: "https://axec.example.com",
  clientId: "public-client-id",
  redirectUri: "http://127.0.0.1:3000/callback",
  storage: new MemoryStorage(),
});


auth.startAuthorization(resource, { scopes: ["mcp:invoke"] });

Complete the browser login, connect any required upstream account, review the displayed Connector authority, and accept consent. In your callback route, redeem the code:

const token = await auth.completeCallback(window.location.href);
console.log(token.connector_outcomes);

For an autonomous confidential Application, use the autonomous gateway interface instead. Do not use autonomous authority for User-owned Connections.

2. Inspect the admitted authority

Section titled “2. Inspect the admitted authority”

For delegated access, reload the current GrantBundle rather than trusting token claims alone:

const authority = await auth.grantBundle(resource);
console.log(authority.root_mode, authority.grants);

Confirm that the intended Connector has an active Grant with mcp usage. If it is absent, re-run authorization with the correct Connector selection or ask the administrator to check the gateway attachment.

3. Discover and call one tool

Section titled “3. Discover and call one tool”

Point a standard Streamable HTTP MCP client at the gateway Resource. Every request is an independently authenticated POST; Axec does not issue an Mcp-Session-Id.

tools/list
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}

Tool names use <connector_key>__<capability_key>. Select one listed read-only capability for the first invocation:

tools/call
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "internal-tickets__tickets.list",
    "arguments": { "state": "open" }
  }
}

Send the gateway bearer on both requests:

Authorization: Bearer <gateway-access-token>
Accept: application/json, text/event-stream
Content-Type: application/json

Use a capability actually returned by tools/list; the illustrative name above is not a provider catalog entry.

4. Verify the result and evidence

Section titled “4. Verify the result and evidence”

In the Axec Console, open Applications, select the gateway Application, and inspect Tool calls. Verify:

  • the decision is allow;
  • the User or Application principal is correct;
  • the Connector and capability match the request;
  • the upstream outcome is correlated to the decision; and
  • any Data Protection outcome reports only safe profile and redaction metadata.

An HTTP token that is cryptographically valid is not sufficient on its own. Repeating the call after revoking the Grant, Connection, attachment, or issuing credential must fail when Axec reloads live authority.

Troubleshooting

Section titled “Troubleshooting”
Symptom Check
OAuth rejects the request Exact client ID, redirect URI, gateway Resource, PKCE S256, and mcp:invoke
Connector does not appear Active gateway attachment, Connector state, and User Connection readiness
tools/list is empty Current Grant usage, discovered capability contract, and attachment ceiling
Call returns pending A step-up policy matched; poll the ActionRequest and retry only after approval
data_protection_unavailable Axec withheld a result it could not safely sanitize; it did not return the raw result

Cleanup

Section titled “Cleanup”

Revoke the test Grant or the complete GrantBundle. Revoke a disposable Connection separately if the quickstart created one. Do not delete or rotate shared Application credentials unless the administrator created them specifically for this exercise.

Continue

Section titled “Continue”