MCP authentication and configuration guide

Last updated 09/15/2026

MCP authentication and configuration guide

Date written: 2026-07-02. Scope: MCP management on the te-claude web UI, use in conversations, materialization of the workspace .mcp.json, and integration of collaboration MCPs such as Slack / Feishu / Lark / DingTalk.

1. General principles

MCP integration in te-claude follows two paths:

1. Web conversation path: users configure MCPs on the MCP management page, and the credentials are stored in the te-claude DB. At conversation runtime, MCPs are resolved by user, company, and system visibility, and the credentials are injected.
2. Sandbox / workspace path: the workspace .mcp.json materializes only MCP configurations that are safe to write to disk. OAuth tokens, App Secrets, and sensitive headers are not written to .mcp.json; sensitive MCPs obtain their runtime configuration indirectly through a managed helper/proxy.

Therefore:

• Web conversations do not depend on the workspace .mcp.json.
• .mcp.json mainly serves Claude Code / terminal tools in My Sandbox.
• OAuth credentials on the web and local Claude Code OAuth credentials are not shared automatically.
• Users need to authenticate the first time they use an OAuth MCP; later conversations reuse the credentials in the DB.
• When credentials expire or are judged invalid by the upstream service, the MCP status changes to Reauth needed, and the MCP should not be disabled automatically.

2. Supported transports

Transport	Use cases	Custom MCP on the web	Connection template	Description
streamable-http	New remote MCPs, DingTalk MCP, Slack hosted MCP	Supported	Supported	Recommended. Claude Code also recognizes this type, so no conversion to http is needed.
http	Compatible with some remote MCPs	Supported	Depends on the template	Suitable for server-side HTTP MCPs.
sse	Legacy SSE MCPs	Supported	Depends on the template	Suitable for MCPs that still use the SSE transport.
stdio	Local/managed command-based MCPs, such as Feishu/Lark OpenAPI MCP	Not available in custom mode	Supported	Regular users don't fill in command/args directly; a managed helper configuration is generated through a connection template.

By default, custom MCPs support only URL-based MCPs: sse, http, and streamable-http. stdio is available only through controlled connection templates, to avoid the uncontrollable risks of users writing commands, paths, and keys by hand.

3. Supported authentication types

Authentication type	Applicable MCPs	Configuration	Credential storage	Expiration handling
Manual header	Regular private MCPs, DingTalk URL-based MCPs, some self-hosted gateways	Enter key/value in the header row editor; encryption is optional	Regular headers are saved with the configuration; encrypted headers are stored in secretJson	The user updates the header or URL
OAuth 2.0	Slack hosted MCP, remote MCPs that support standard OAuth	Configure the OAuth Client ID/Secret, scopes, authorization URL, token URL, resource, etc.	User OAuth tokens are encrypted and stored in McpCredential	Reauthentication is triggered when the token expires or on invalid_token
App Secret	Feishu OpenAPI MCP, Lark OpenAPI MCP	Enter the App ID, App Secret, and tools in the connection template	The App Secret is encrypted and stored in secretJson	An admin updates the configuration when the App Secret becomes invalid
No additional authentication	MCPs whose URL already contains a temporary key, such as some DingTalk MCP gateway URLs	The URL itself carries the key	The URL is saved as a regular configuration	Copy the URL generated by DingTalk again when the URL/key becomes invalid

Header row editor rules

Headers in the MCP form use a unified row editor:

• Each row contains key, value, Encrypt, an add button, and a delete button.
• key is required and must follow the HTTP header token format. It cannot contain spaces, colons, or control characters.
• value is required. To delete a header, delete the entire row.
• Header keys are deduplicated case-insensitively; Authorization and authorization are treated as duplicates.
• After you turn on Encrypt, the value is stored encrypted.
• When you edit an existing encrypted value, ******** means the original value is kept; if you change it to *, *********, 1, or similar, it is saved as the actual new value.

4. General OAuth MCP authentication flow

The goal of OAuth MCP: authentication is triggered the first time a user uses it, and after authentication, te-claude saves the user's credentials and automatically injects them into later conversations.

4.1 Configuration

When an admin or user creates an OAuth MCP, they need to configure:

• Service Name: the runtime name in English, for example slack.
• Display Name: can be in Chinese, for example Slack MCP.
• Transport Type: usually streamable-http or http.
• Service URL: the MCP endpoint, for example https://mcp.slack.com/mcp.
• OAuth Client ID。
• OAuth Client Secret。
• scopes。
• Authorization URL.
• Token URL.
• OAuth resource (if required by the service provider).

Regular users don't need to fill in providerKey. providerKey is an internal system field and can be written only by system templates or connection templates.

4.2 Callback URL

The OAuth callback URL must use the domain of the current te-claude deployment and cannot use localhost.

Format:

https://<te-claude-host>/<basePath>/api/mcp-auth/callback

If the deployment has a base path, such as /agent, the example is:

https://example.com/agent/api/mcp-auth/callback

The redirect URI configured in the service provider's console must match the redirect URI that te-claude uses when it initiates authentication.

4.3 First use

When a user selects an OAuth MCP in a conversation:

1. te-claude checks whether the user already has valid credentials.
2. If the user is not authenticated or needs to reauthenticate, the message is blocked before it is sent.
3. The page opens an OAuth authentication window.
4. The user completes authorization on the service provider's side.
5. The service provider calls back the te-claude callback.
6. te-claude saves the token and either shows a lightweight success page in the authentication window or closes it automatically.
7. The main page polls the authentication status and refreshes the MCP status to Authenticated.
8. The user resends the message, and the MCP is injected at runtime.

4.4 Credential expiration and reauthentication

OAuth credentials may expire. Common reasons include:

• The access token expires.
• The refresh token expires or is revoked.
• The user revokes authorization on the service provider's side.
• The service provider returns invalid_token.
• An admin changes the OAuth App scopes or permissions.

Handling:

• When credentials expire or become invalid, te-claude marks the MCP as Reauth needed.
• Reauth needed doesn't mean disabled; the MCP can still be selected in conversations.
• The authentication window is triggered the next time a message is sent.
• The MCP is considered disabled only when the user turns it off or selects Disconnect auth.

5. Slack MCP configuration

5.1 Recommended setup

Slack uses the official hosted MCP:

https://mcp.slack.com/mcp

Slack is integrated through a Connection template. The creator needs to configure their own Slack App OAuth Client ID / Client Secret / scopes, and each user completes personal OAuth authorization the first time they use it.

A Slack OAuth App is closely tied to a workspace / customer. A company-level Slack MCP usually uses a Slack App maintained centrally by the company, while a personal Slack MCP is usually used for personal testing or for connecting a personal workspace.

Recommended usage:

Scope	Use cases	Authentication experience
Company MCP	The company maintains a Slack App centrally for users in the same company	A company admin creates the template configuration; each user completes OAuth authorization individually on first use.
Personal MCP	Personal testing or connecting a personal workspace	After creating it, the user can authenticate right away or on first use.

5.2 Slack App settings

Confirm the following in the Slack App settings:

• A Slack App has been created.
• The OAuth redirect URL has been configured:

https://<te-claude-host>/<basePath>/api/mcp-auth/callback

• The scopes cover the Slack tools you actually use.
• MCP / App Assistant capabilities are enabled for the Slack App.
• Writing a static xoxp token into a header is not recommended as a long-term solution.

5.3 te-claude configuration

Recommended configuration for a system MCP:

On the MCP management page, select:

Connection template -> Slack MCP

Fixed or recommended template settings:

Field	Example
Service Name	slack
Display Name	Slack MCP
Transport	streamable-http
Auth Mode	OAuth 2.0
URL	https://mcp.slack.com/mcp
OAuth Client ID	Client ID of the Slack App
OAuth Client Secret	Client Secret of the Slack App
scopes	Select Slack MCP tool permissions as needed

The OAuth Client ID / Client Secret of a Slack MCP is stored in the encrypted configuration of the current MCP instance. The Slack Channel configuration is used for IM channel binding, while the Slack MCP configuration is used for MCP tool authentication; the two are managed independently.

When users use it:

1. Select Slack MCP in the conversation.
2. If you are not authenticated, the page triggers OAuth automatically.
3. After authentication, resend the message.

If you create a personal Slack MCP, te-claude asks whether to go to Slack for authentication right after it is saved. Selecting Later doesn't affect the configuration, and authentication is still triggered on first use.

6. Feishu OpenAPI MCP configuration

For Feishu, the OpenAPI MCP connection template is currently recommended. An admin or user configures the App ID / App Secret of a custom app and the tool list.

6.1 Create a Feishu custom app

Create a custom app on the Feishu Open Platform:

1. Create the app and record its App ID and App Secret.
2. Enable the bot capability.
3. Set the app's availability.
4. Configure the contacts permission scope.
5. Apply for OpenAPI permissions according to your actual tool list. For examples, see 6.3 Example tool list and 6.4 Tools and permissions.
6. Publish the app and wait for the permissions to take effect.
7. If you use the user OAuth / UAT approach, you also need to configure a redirect URL; the OpenAPI App Secret template itself usually doesn't depend on a user OAuth redirect.

6.2 te-claude connection template

On the MCP management page, select:

Connection template -> Feishu OpenAPI MCP

Fill in:

Field	Description
Service Name	The runtime name in English, for example feishu-openapi
Display Name	For example, Feishu OpenAPI MCP
App ID	App ID of the Feishu custom app
App Secret	App Secret of the Feishu custom app
Tool list	Comma-separated OpenAPI tool names or presets

Fixed by the template:

Field	Fixed value
Transport	stdio
Auth Mode	App secret
Category	Developer Tools

6.3 Example tool list

If your goal is to "create groups, add owners, send reports, read messages, and save results to Base", you can choose from the following tools:

im.v1.chat.create,
im.v1.chat.list,
im.v1.chatMembers.get,
im.v1.message.create,
im.v1.message.list,
wiki.v2.space.getNode,
wiki.v1.node.search,
docx.v1.document.rawContent,
drive.v1.permissionMember.create,
docx.builtin.import,
docx.builtin.search,
bitable.v1.app.create,
bitable.v1.appTable.create,
bitable.v1.appTable.list,
bitable.v1.appTableField.list,
bitable.v1.appTableRecord.search,
bitable.v1.appTableRecord.create,
bitable.v1.appTableRecord.update,
contact.v3.user.batchGetId

You can also start with a broader preset:

preset.default,preset.im.default,preset.doc.default

For production use, switch to an explicit tool list to make permission auditing and risk control easier.

6.4 Tools and permissions

API name	Description	Required permissions
im.v1.chat.create	Create a group	Create group (im:chat:create)
im.v1.chat.list	Get the list of groups the user or bot is in	Obtain and update group information (im:chat)
im.v1.chatMembers.get	Get the list of group members	Obtain and update group information (im:chat)
im.v1.message.create	Send messages	Obtain and send messages in private and group chats (im:message)
im.v1.message.list	Get chat history messages	Obtain and send messages in private and group chats (im:message)
wiki.v2.space.getNode	Get wiki space node information	View, edit, and manage Wiki (wiki:wiki)
wiki.v1.node.search	Search Wiki	View Wiki (wiki:wiki:readonly)
docx.v1.document.rawContent	Get the plain-text content of a document	Create and edit new-version documents (docx:document)
drive.v1.permissionMember.create	Add collaborator permissions	View, edit, and manage Wiki (wiki:wiki)
docx.builtin.import	Import documents, including uploading media/files, creating import tasks, and querying import task results	View, comment on, edit, and manage Base (bitable:app); view, comment on, edit, and manage all files in Drive (drive:drive); view and create document import tasks (docs:document:import)
docx.builtin.search	Search documents	View, comment on, edit, and manage all files in Drive (drive:drive)
bitable.v1.app.create	Create a Base	View, comment on, edit, and manage Base (bitable:app)
bitable.v1.appTable.create	Add a data table	View, comment on, edit, and manage Base (bitable:app)
bitable.v1.appTable.list	List data tables	View, comment on, edit, and manage Base (bitable:app)
bitable.v1.appTableField.list	List fields	View, comment on, edit, and manage Base (bitable:app)
bitable.v1.appTableRecord.search	Search records	View, comment on, edit, and manage Base (bitable:app)
bitable.v1.appTableRecord.create	Add a record	View, comment on, edit, and manage Base (bitable:app)
bitable.v1.appTableRecord.update	Update a record	View, comment on, edit, and manage Base (bitable:app)
contact.v3.user.batchGetId	Get user IDs by mobile number or email	Obtain user ID via mobile number or email (contact:user.id:readonly)

6.5 Common limitations

• A tool being available doesn't mean its permissions are in effect; the Feishu app must apply for and publish the permissions.
• Contacts APIs are also restricted by the app's availability and contacts permission scope.
• contact.v3.user.batchGetId can only exchange a mobile number or email for a user ID; it doesn't support fuzzy search by name.
• Actions such as creating groups and sending messages usually require the bot capability to be enabled.
• The bot must be in the target group, or the app must have the corresponding group operation permissions.

7. Lark OpenAPI MCP configuration

Lark OpenAPI MCP has the same structure as Feishu OpenAPI MCP; the difference is that the international Open Platform uses a different domain.

The te-claude Lark template automatically appends:

["--domain", "https://open.larksuite.com"]

Users don't need to fill in the domain manually.

Configuration steps:

1. Create a custom app in Lark Developer.
2. Get the App ID / App Secret.
3. Enable the bot capability.
4. Configure the app's availability and permissions.
5. Apply for the OpenAPI permissions that match the tool list.
6. In te-claude, select the Lark OpenAPI MCP connection template.
7. Fill in the App ID, App Secret, and tools.

Recommended service name:

lark-openapi

The example tool list can reuse the tool names of Feishu OpenAPI MCP. Permission names are subject to what the Lark Developer console actually shows.

8. DingTalk MCP configuration

For DingTalk MCP, the URL-based connection template is currently recommended, because the DingTalk MCP marketplace contains multiple MCPs whose names and URLs are generated by DingTalk and should not be fixed in te-claude.

8.1 Enable in the DingTalk MCP marketplace

Entry:

https://aihub.dingtalk.com/#/mcp

In the DingTalk MCP marketplace, select the MCPs you need, such as "Robot Message" and "DingTalk Group Chat". After enabling them, copy the configuration JSON.

Example:

{
  "mcpServers": {
    "机器人消息": {
      "type": "streamable-http",
      "url": "https://mcp-gw.dingtalk.com/server/2de***"
    }
  }
}

8.2 Configure in te-claude

On the MCP management page, select:

Connection template -> DingTalk MCP

Fixed by the template:

Field	Fixed value
Transport	streamable-http
Auth Mode	Manual header
Category	Developer Tools

You need to fill in:

Field	Example	Description
Service Name	dingtalk-robot-message	Only English letters, digits, underscores, or hyphens; used as the runtime name.
Display Name	Robot Message	You can use the Chinese key under mcpServers in the DingTalk JSON.
Service URL	https://mcp-gw.dingtalk.com/server/2de***	Copy the url generated by DingTalk.

If the DingTalk URL already contains a key, you usually don't need an additional header. Treat the URL as sensitive information and don't paste it publicly into documents, issues, or code repositories.

8.3 DingTalk limitations

• The DingTalk group chat MCP may require members to be users in your organization.
• Creating groups and sending messages are restricted by your organization's security policies.
• Some MCPs need the contacts capability to resolve names to DingTalk userId values.
• When the URL or authorization becomes invalid, go back to the DingTalk MCP marketplace to regenerate the configuration.

9. Feishu remote MCP is not offered as a connection template

Feishu remote MCP requires users to obtain one of the following headers themselves:

• X-Lark-MCP-UAT: user identity token.
• X-Lark-MCP-TAT: app identity token.

You also need:

• Content-Type: application/json
• X-Lark-MCP-Allowed-Tools

Obtaining and refreshing tokens and diagnosing permissions on this path is relatively demanding, so it is currently not offered as a te-claude connection template.

If you really need it, you can configure it manually as a regular custom URL MCP:

Field	Example
Transport	streamable-http
Service URL	https://mcp.feishu.cn/mcp
Header	X-Lark-MCP-UAT or X-Lark-MCP-TAT
Header	X-Lark-MCP-Allowed-Tools

However, Feishu / Lark OpenAPI MCP remains the preferred recommendation for productized use.

10. Scope and permissions

Scope	Visibility	Who can create	Use cases
System MCP	Visible across the site	System seed / admin preset	Globally preset MCPs that don't depend on a customer's private OAuth App / App Secret.
Company MCP	Visible within the same company	Company admin	Company-level App Secrets such as Feishu/Lark OpenAPI.
Personal MCP	Visible only to the creator	All signed-in users	Personal testing, personal DingTalk URLs, personal OAuth MCPs.

The connection template entry is visible to all signed-in users. Non-admins can use templates to create personal MCPs; creating company-level MCPs still requires admin permissions.

11. Workspace .mcp.json rules

When a workspace saves MCPs, te-claude generates .mcp.json based on the MCP type:

11.1 Regular URL MCP

Regular non-sensitive URL MCPs can be written directly:

{
  "mcpServers": {
    "dingtalk-robot-message": {
      "type": "streamable-http",
      "url": "https://mcp-gw.dingtalk.com/server/2de***"
    }
  }
}

11.2 Managed MCP

For OAuth, App Secret, and sensitive-header MCPs, plaintext credentials are not written; a managed helper is written instead:

{
  "mcpServers": {
    "slack": {
      "type": "stdio",
      "command": "node",
      "args": ["/app/dist/mcp/managed-mcp-remote.js", "--server-id", "system-mcp-slack"]
    }
  }
}

Feishu/Lark OpenAPI MCPs also write a helper instead of writing the App Secret to the file.

12. Troubleshooting

12.1 Conversation shows "No MCP tools"

Check:

• Whether the corresponding MCP is selected in the conversation input box.
• Whether the MCP is enabled.
• Whether the OAuth MCP is authenticated or needs reauthentication.
• Whether the tool list loads properly.
• Whether the upstream MCP URL is reachable from the te-claude server.
• For Feishu/Lark OpenAPI, whether the app permissions have been applied for and published.

12.2 Failed to list tools

Common causes:

• The URL is wrong.
• The server network is unreachable, for example ECONNREFUSED, ENOTFOUND, or ETIMEDOUT.
• The upstream returns HTML instead of an MCP JSON-RPC response.
• The OAuth token is invalid.
• The Feishu/Lark App Secret is wrong.
• The Feishu/Lark tool name doesn't exist or permissions are insufficient.

An unreachable network is not an authentication problem. First confirm that the te-claude deployment environment can access the MCP address.

12.3 Feishu/Lark tool exists but calls fail

Check:

• Whether the app has been published.
• Whether the permissions have been approved.
• Whether the bot capability is enabled.
• Whether the app's availability covers the target users.
• Whether the contacts permission scope covers the target users.
• Whether the bot is in the target group.
• Whether the tool list includes the OpenAPI tool names that are actually called.

12.4 DingTalk MCP saves but calls fail

Check:

• Whether the complete URL was copied.
• Whether the key in the URL has expired.
• Whether the organization's security policy allows the action.
• Whether creating a group or sending a direct message requires a DingTalk userId.
• Whether the MCP has been enabled in the DingTalk MCP marketplace.

12.5 Slack still shows invalid after successful authentication

Check:

• Whether the Slack App redirect URL matches the te-claude callback.
• Whether MCP / App Assistant capabilities are enabled for the Slack App.
• Whether the scopes cover the tool calls.
• Whether the user has revoked authorization.
• Whether an old token or a static token approach is being used.

13. Recommended integration order

1. Slack MCP: validates general OAuth MCP, user authentication, and reauthentication after credentials expire.
2. Feishu OpenAPI MCP: validates enterprise IM / document / Base workflows in mainland China.
3. Lark OpenAPI MCP: validates enterprise customers on the international version of Lark.
4. DingTalk URL-based MCP: validates the setup experience with URLs generated in the DingTalk MCP marketplace.
5. Regular custom MCP: covers customers' self-built MCPs and third-party MCPs.

14. Minimum acceptance checklist

After configuring an MCP, verify at least the following:

• The MCP management page can save the configuration.
• The tool list can be read properly, or errors clearly explain the cause.
• The MCP can be selected in conversations.
• An unauthenticated OAuth MCP triggers the authentication window instead of having the Agent reply "No tools".
• After authentication, the MCP status changes to Authenticated.
• The workspace .mcp.json doesn't contain plaintext OAuth tokens, App Secrets, or sensitive headers.
• The tool list of the Feishu/Lark OpenAPI MCP matches the app permissions.
• The service name of the DingTalk MCP is in English, and the display name can be in Chinese.

---

Related pages and next steps

• Find available tool services: MCP.
• Configure tools for an Agent: Agent.
• Use tools in conversations: Conversations.
• Configure chatbot channels: Channel Management.