Skip to main content

AI Client Connection Guide (MCP)

How to connect an MCP-capable AI client to the AGENTIC STAR MCP endpoint. With the chat set, you ask an agent to do work; with the project set, you create and run projects, handle approval requests, and more. For the detailed specification of tools and scopes, see the MCP API Reference.

What You Need​

  • The AI client you use (Claude Code, Codex, Cursor, VS Code, or Claude)
  • To connect as a person: an application (Client ID) created in the Console
  • To connect as a system integration: a system integration created in the Console, and its API key

Install the Plugin (Recommended)​

You can install the AGENTIC STAR plugin in Claude Code, Codex, and Claude. After installing it, ask "Connect to AGENTIC STAR", and it guides you through the connection.

IncludedWhat it does
agenticstar-connectGuides you through connecting to the AGENTIC STAR MCP endpoint
agenticstar-projectsCreates projects, finds and fixes failures, handles approval requests, and reads results
  • The plugin does not include MCP connection settings. Set your Client ID or API key by following its guidance
  • It is a different plugin from the Marketplace edition's. For the SaaS edition, use the plugin on this page
  • Current version: 3.2.0

Download the plugin (agenticstar.zip)

In the folder where you extracted the zip, run the following (Claude Code 2.1.292 or later).

curl
claude plugin install agenticstar --marketplace ./agenticstar

Choose How to Connect​

Who uses itHow to connectWhat to prepare in the Console
A person (with their own account)Sign in from the clientAn application (Client ID)
A system (system integration)Put a fixed API key in Authorization: BearerAn API key of a system integration

The MCP endpoint is shown below. Select the tool sets to use with toolsets (see Tool Sets).

https://api.fd.agenticstar.tm.softbank.jp/api/v1/mcp?toolsets=chat,project
About the configuration examples

The settings on this page are examples for reference. How to configure a client can change between its versions. For the latest instructions, see each client's documentation (Claude Code, Codex, Cursor, VS Code, Claude). For other MCP clients, set the endpoint, Client ID, and redirect URI by following that client's documentation.

Connect as a Person​

1. Create an Application in the Console​

Create it by following Console Guide — Steps to Create an Application.

  • Application type: Select "Mobile / Native" (it has no Client Secret and signs in with PKCE)
  • Redirect URI: Register the redirect URI of each client you use (see the table below)
  • Scopes: Select mcp:connect and the scopes of the tools you use. The scope for each tool is in MCP API Reference — Provided Tools (for example, chat:exec for the chat set, project:read to read projects)
ClientRedirect URI to register
Claude Codehttp://localhost:<port>/callback (the port you pass to --callback-port)
CodexThe value you set in callback_url (for example, http://localhost:<port>/callback)
Cursor (desktop app)http://localhost:8787/callback
VS Codehttp://127.0.0.1:33418/ and https://vscode.dev/redirect
Claudehttps://claude.ai/api/mcp/auth_callback

2. Configure the Client and Sign In​

Replace <client_id> with the Client ID of the application you created.

curl
claude mcp add --scope user --transport http \
--client-id <client_id> --callback-port <port> \
agenticstar 'https://api.fd.agenticstar.tm.softbank.jp/api/v1/mcp?toolsets=chat,project'

Open /mcp in Claude Code and choose to authenticate agenticstar, or run claude mcp login agenticstar. The sign-in page opens in the browser.

Connect as a System Integration​

  1. Create it by following Console Guide — System Integration Creation Steps. Select mcp:connect and, depending on the operations you use, project:read and project:run, and set the project restriction
  2. Issue an API key on the system integration's detail page (see Console Guide — API Key)
  3. Set Authorization: Bearer <API key> in the client. You don't need to get a new token
curl
claude mcp add --scope user --transport http agenticstar-system \
'https://api.fd.agenticstar.tm.softbank.jp/api/v1/mcp?toolsets=project' \
--header "Authorization: Bearer <API key>"

A system integration can use the four operations of the project set (list of project_read, get of run_read, start_run and fire_trigger of project_run) and list_personas of the chat set (use toolsets=chat,project for list_personas). It can only work with projects within its project restriction. Claude has no way to connect as a system integration.

Use It Safely​

  • Operations that write: When you let the AI create, change, or delete projects, or decide approval requests, use the client's permission settings so that you can check each operation before it runs (Claude Code asks for permission every time before it decides an approval request. Claude lets you set permissions per tool. For other clients, see the client's documentation)
  • Read-only use: For read-only use, create an application whose scopes are only mcp:connect and project:read
  • API key: Treat an API key as a secret, the same as a Client Secret. Don't paste it into chats or documents
  • If credentials leak: When people connect, delete the application in the Console. For a system integration, delete the API key or disable the system integration. It can take up to about 1 minute to take effect (see Console Guide — If Credentials Leak)

Troubleshooting​

  • Tool sets: Without toolsets, only the chat set is available. Specify project to use the project set
  • Redirect URI mismatch: If the sign-in page shows a redirect URI error, check that the client's redirect URI matches the one registered in the Console (for Claude Code and Codex, the port)
  • Missing scopes: When you call a tool without the required scope, a tool error returns the scope needed and what to do next. For a person's application, add the scope in the Console and sign in again
  • System integration scope: A system integration can only work with projects within its project restriction
  • Rejected for a system integration: This endpoint is not available to client credentials (403) is returned when a system integration calls an operation it cannot use. To use that operation, connect as a person
  • Front-end protection (WAF): Depending on the input, a request can be stopped by the front-end protection. In that case the HTTP status is 403, and in the JSON body error.code is waf_blocked. When there is a reference number, it is in error.reference
  • When the tools change: When an AGENTIC STAR update changes the tools, reconnect (in Claude Code, /mcp; in Claude, refresh the tool list from the connector's menu)

See Also​