Skip to main content

Connect your AI assistant

Your AI assistant reads Astrolabe's catalog for you: a component, its owner, what belongs to a system. It reads with your rights, and only reads. Nothing secret to copy: the first time, the assistant opens an Astrolabe page where you approve it.

Your administrator must have turned the MCP server on: see Turn on the MCP server.

🔌 Get the configuration​

  1. At the top right, click your name, then My Account.

  2. Click the My accounts tab.

  3. On the MCP card, click Connect. The window Connect my AI assistant opens.

  4. Under the name of your assistant, click Copy:

    • Claude Code: a command, for example claude mcp add --transport http astrolabe https://astrolabe.example.com/api/mcp-actions/v1/astrolabe

    • VS Code (.vscode/mcp.json): a block to paste in the .vscode/mcp.json file of your project:

      {
        "servers": {
          "astrolabe": {
            "type": "http",
            "url": "https://astrolabe.example.com/api/mcp-actions/v1/astrolabe"
          }
        }
      }

  5. Click Close.

🤖 Approve your assistant​

  1. Claude Code: run the copied command in a terminal, then in Claude Code type /mcp, choose astrolabe and Authenticate. VS Code: save .vscode/mcp.json, then click Start above astrolabe.

  2. Your browser opens an Astrolabe page titled Authorization: it names the assistant and the address it will come back to. Check them, then click Authorize.

  3. Back in your assistant, ask it something about your catalog, for example: "Who owns the component payment-service in Astrolabe?"

✅ That's it! In My Account › My accounts, the MCP card now says Connected.

💬 What to ask your assistant​

Ask in your own words; your assistant picks what to read in Astrolabe. For example:

  • "Who owns the component payment-service in Astrolabe?"
  • "Which components belong to the system checkout in Astrolabe?"
  • "List the APIs the group platform-team owns in Astrolabe."
  • "Which components of the catalog are still experimental?"
  • "Find a skill in Astrolabe to write release notes, and tell me how to install it."
  • "Is this catalog-info.yaml valid for Astrolabe?" (paste the file, or name it in your project)
  • "What kinds of entities does the Astrolabe catalog know?"
  • "What are my unread notifications in Astrolabe?"

Your assistant reads, it never changes the catalog: to register a component or edit an entity, use Astrolabe.

✂️ Revoke an assistant​

  1. In My Account › My accounts, on the MCP card, click Configure.

  2. Under Approved assistants, each assistant shows the day you approved it and the day it last read Astrolabe. On the one to cut, click Revoke.

  3. In the window Revoke … ?, click Revoke. The message … can no longer read Astrolabe appears.

Its next call is refused. To use it again, approve it once more (steps above).

❓ Frequently asked questions​

What can my assistant read? What you can read in the catalog, and your own notifications. It changes nothing: it does not even mark a notification as read.

Can my assistant use its access elsewhere? No. The access you give it only opens Astrolabe's MCP server: any other call is refused.

Do I need a token? No. You approve the assistant on an Astrolabe page; it never sees your password.

Can I connect several assistants? Yes. Each one appears under Approved assistants, and you revoke each one on its own.

Which assistants work? Claude Code and VS Code.

🛠️ Troubleshooting​

The assistant says "This access was revoked in My account. Sign in again from your assistant." You (or your administrator) revoked it. Approve it again: in Claude Code, /mcp › astrolabe › Authenticate.

The assistant says "Astrolabe's MCP server is turned off by your administrator." Ask your administrator to turn it on.

There is no MCP card in My accounts. The server is off on your instance: ask your administrator.

The card says "Not verified" and the window "Your assistants could not be read: Astrolabe did not answer." Astrolabe did not answer for a moment. Reload the page in a minute.

The assistant cannot reach Astrolabe at all. Astrolabe may be behind a firewall or Cloudflare Access: your administrator lets the paths of Behind a firewall through.